infrastructure-llm git:20260507.a8ed8a2A

Immutable. This exact content is served forever at /api/v1/blob/cce071ca00a98bde.

---
name: infrastructure-llm
description: Skill for the LLM infrastructure module providing local Large Language Model integration via Ollama. Covers client initialization, prompt templates, output validation, manuscript review generation, conversation context, and CLI usage. Use when querying LLMs, generating manuscript reviews, validating LLM outputs, or managing Ollama models.
---

# LLM Module

Local Large Language Model integration for research assistance via Ollama.

## Module Structure

```mermaid
flowchart LR
    LLM[/llm//]
    LLM --> CORE[/core<br/>client · config · context/]
    LLM --> TPL[/templates<br/>prompt templates for research/]
    LLM --> VAL[/validation<br/>output quality validation/]
    LLM --> RV[/review<br/>manuscript review generation/]
    LLM --> PR[/prompts<br/>fragment composition system/]
    LLM --> UT[/utils<br/>Ollama server management/]
    LLM --> CLI[/cli<br/>command-line interface/]

    classDef d fill:#0f172a,stroke:#0f172a,color:#fff
    classDef pkg fill:#1e3a8a,stroke:#0f172a,color:#fff
    class LLM d
    class CORE,TPL,VAL,RV,PR,UT,CLI pkg
```

## LLM Client (`core/client.py`)

```python
from infrastructure.llm import LLMClient, OllamaClientConfig, GenerationOptions

# Initialize with defaults
client = LLMClient()

# Custom configuration
config = OllamaClientConfig(default_model="gemma3:4b", temperature=0.7)
client = LLMClient(config)

# Generate a response
response = client.query("Summarize this paper...", options=GenerationOptions(
    max_tokens=2000,
    temperature=0.3,
))
```

## Conversation Context (`core/context.py`)

```python
from infrastructure.llm import ConversationContext, Message

context = ConversationContext()
context.add(Message(role="user", content="What is active inference?"))
context.add(Message(role="assistant", content="Active inference is..."))
```

## Prompt Templates (`templates/`)

Pre-built research task templates:

```python
from infrastructure.llm import (
    get_template, ResearchTemplate, PaperSummarization,
    ManuscriptExecutiveSummary, ManuscriptQualityReview,
    ManuscriptMethodologyReview, ManuscriptImprovementSuggestions,
    ManuscriptTranslationAbstract,
)

# Get a template by name
template = get_template("paper_summarization")

# Use specific template classes
summary_template = ManuscriptExecutiveSummary()
prompt = summary_template.format(manuscript_text=text)
```

## Output Validation (`validation/`)

Validation was decomposed into module-level functions in v0.6.0 — the
previous `OutputValidator` class is gone; call the individual checks
directly.

```python
from infrastructure.llm import (
    detect_repetition, is_off_topic,
    check_format_compliance, validate_section_completeness,
    calculate_unique_content_ratio, deduplicate_sections,
)

# Individual checks
if is_off_topic(response_text):
    logger.warning("Response appears off-topic")

if detect_repetition(response_text):
    logger.warning("Response contains repeated content")

ratio = calculate_unique_content_ratio(response_text)
```

## Manuscript Review Generation (`review/`)

```python
from infrastructure.llm import (
    create_review_client, select_and_start_ollama_model, warmup_model,
    extract_manuscript_text, generate_review_with_metrics,
    generate_executive_summary, generate_quality_review,
    generate_methodology_review, generate_improvement_suggestions,
    generate_translation, save_review_outputs,
)

# Full review workflow
client = create_review_client()
warmup_model(client)
text = extract_manuscript_text(manuscript_dir)

executive = generate_executive_summary(client, text)
quality = generate_quality_review(client, text)
methodology = generate_methodology_review(client, text)
suggestions = generate_improvement_suggestions(client, text)

save_review_outputs(output_dir, executive=executive, quality=quality,
                    methodology=methodology, suggestions=suggestions)
```

## Ollama Utilities (`utils/`)

```python
from infrastructure.llm import (
    is_ollama_running, start_ollama_server, ensure_ollama_ready,
    get_model_names, select_best_model,
    select_small_fast_model, preload_model, check_model_loaded,
)

# Check and start Ollama
if not is_ollama_running():
    start_ollama_server()

ensure_ollama_ready()
models = get_model_names()
best = select_best_model()
```

## Prompt Composition (`prompts/`)

```python
from infrastructure.llm import PromptFragmentLoader, PromptComposer

loader = PromptFragmentLoader()
composer = PromptComposer(loader)
prompt = composer.compose(task="review", context=manuscript_text)
```

## CLI Usage

```bash
# Query the LLM
uv run python -m infrastructure.llm.cli.main query "What is machine learning?"

# Check Ollama status
uv run python -m infrastructure.llm.cli.main check

# List available models
uv run python -m infrastructure.llm.cli.main models
```