src.llm_interpreter.llm.engine

LLM engine for AMMM report generation.

This module provides a deterministic LLM interface with caching, structured-first prompting, and support for multiple providers.

Author: AMMM Team Created: 2025-04-10 Last Modified: 2025-04-10

Module Contents

class src.llm_interpreter.llm.engine.CachedResponse

Represents a cached LLM response.

class src.llm_interpreter.llm.engine.LLMCache(cache_dir: pathlib.Path)

Simple file-based cache for LLM responses.

Uses prompt hash as key to enable deterministic caching.

get(prompt: str, model: str, temperature: float) → str | None

Get cached response if available.

Parameters:

  • prompt – The prompt text

  • model – Model identifier

  • temperature – Temperature parameter

Returns:

Cached response or None

set(prompt: str, response: str, model: str, temperature: float)

Cache a response.

Parameters:

  • prompt – The prompt text

  • response – The LLM response

  • model – Model identifier

  • temperature – Temperature parameter

clear()

Clear all cached responses.

class src.llm_interpreter.llm.engine.LLMEngine(model: str = 'gpt-4', temperature: float = 0.1, cache_dir: pathlib.Path | None = None, use_cache: bool = True)

LLM engine with caching and structured prompting support.

Supports multiple providers (configurable via environment or config). Implements deterministic generation with low temperature and caching.

generate(prompt: str, system_prompt: str | None = None, temperature: float | None = None) → str

Generate text from prompt.

Parameters:

  • prompt – User prompt

  • system_prompt – Optional system prompt

  • temperature – Override default temperature

Returns:

Generated text

extract_json(response: str) → dict[str, Any]

Extract JSON from LLM response.

Handles cases where LLM includes markdown code blocks or extra text.

Parameters:

response – LLM response text

Returns:

Parsed JSON object

Raises:

ValueError – If JSON cannot be extracted

class src.llm_interpreter.llm.engine.StructuredFirstWorkflow(engine: LLMEngine)

Implements structured-first prompting workflow.

Step 1: Extract structured insights from evidence (JSON) Step 2: Generate narrative from structured insights

extract_structured(extraction_prompt: str, system_prompt: str | None = None) → dict[str, Any]

Extract structured insights from evidence.

Parameters:

  • extraction_prompt – Prompt requesting JSON extraction

  • system_prompt – Optional system prompt

Returns:

Extracted structured data as dictionary

generate_narrative(narrative_prompt: str, system_prompt: str | None = None) → str

Generate narrative from structured data.

Parameters:

  • narrative_prompt – Prompt with structured data for narrative generation

  • system_prompt – Optional system prompt

Returns:

Generated narrative text

structured_first_pipeline(extraction_prompt: str, narrative_prompt_template: str, system_prompt: str | None = None) → tuple[dict[str, Any], str]

Execute complete structured-first pipeline.

Parameters:

  • extraction_prompt – Prompt for extracting structured data

  • narrative_prompt_template – Template for narrative prompt (with {structured_data})

  • system_prompt – Optional system prompt

Returns:

Tuple of (structured_data, narrative_text)

src.llm_interpreter.llm.engine.create_llm_engine(model: str = 'gpt-4', temperature: float = 0.1, use_cache: bool = True) → LLMEngine

Create an LLM engine instance with sensible defaults.

Parameters:

  • model – Model identifier

  • temperature – Temperature for generation

  • use_cache – Whether to enable caching

Returns:

LLMEngine instance