feat: implement core D&D helpers logic and system architecture

src/llm/__init__.py

@@ -0,0 +1 @@
+# LLM Module

src/llm/models.py

@@ -0,0 +1,56 @@
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class LoreUpdate(BaseModel):
+    category: str = Field(
+        ...,
+        description="Category of lore: 'NPC', 'Location', 'WorldBuilding', or 'Plot'",
+    )
+    entity_name: Optional[str] = Field(
+        None, description="The name of the NPC, Location, or entity being updated"
+    )
+    content: str = Field(..., description="The actual lore fact or update")
+    context: Optional[str] = Field(
+        None, description="Brief context from the conversation that led to this update"
+    )
+
+
+class InventoryChange(BaseModel):
+    item: str = Field(..., description="Name of the item")
+    quantity: int = Field(1, description="Quantity of the item")
+    action: str = Field(..., description="Either 'added' or 'removed'")
+
+
+class CharacterStateUpdate(BaseModel):
+    character_name: str = Field(
+        ..., description="Name of the character whose state is changing"
+    )
+    hp_change: Optional[int] = Field(
+        None, description="Change in HP (negative for damage, positive for healing)"
+    )
+    status_effects_added: List[str] = Field(
+        default_factory=list,
+        description="List of status effects applied to the character",
+    )
+    status_effects_removed: List[str] = Field(
+        default_factory=list,
+        description="List of status effects removed from the character",
+    )
+    inventory_changes: List[InventoryChange] = Field(
+        default_factory=list,
+        description="List of items added or removed from inventory",
+    )
+
+
+class ExtractionResult(BaseModel):
+    lore_updates: List[LoreUpdate] = Field(
+        default_factory=list, description="List of discovered lore facts"
+    )
+    character_updates: List[CharacterStateUpdate] = Field(
+        default_factory=list, description="List of character state changes"
+    )
+    significant_events: List[str] = Field(
+        default_factory=list, description="List of significant plot points or events"
+    )

src/llm/processor.py

@@ -0,0 +1,92 @@
+import os
+from typing import Any, Dict, Optional
+
+from openai import OpenAI
+from pydantic import ValidationError
+
+from .models import ExtractionResult
+from .prompts import EXTRACTION_SYSTEM_PROMPT, NOISE_FILTER_SYSTEM_PROMPT
+
+
+class LLMProcessor:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        model: str = "gpt-4o",
+    ):
+        """
+        Initializes the LLMProcessor.
+
+        :param api_key: OpenAI API key. If None, it looks for OPENAI_API_KEY in environment variables.
+        :param base_url: OpenAI-compatible base URL (e.g., for vLLM).
+        :param model: The model to use for processing.
+        """
+        self.client = OpenAI(
+            api_key=api_key or os.environ.get("OPENAI_API_KEY"),
+            base_url=base_url or os.environ.get("OPENAI_BASE_URL"),
+        )
+        self.model = model
+
+    def _call_llm(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        response_format: Optional[Any] = None,
+    ) -> str:
+        """
+        Generic method to call the LLM.
+        """
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                response_format=response_format,
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            print(f"LLM Error: {e}")
+            return ""
+
+    def filter_transcript(self, text: str) -> str:
+        """
+        Stage 1: Raw Transcript -> Filtered Text.
+        """
+        return self._call_llm(NOISE_FILTER_SYSTEM_PROMPT, text)
+
+    def extract_structured_data(self, filtered_text: str) -> ExtractionResult:
+        """
+        Stage 2: Filtered Text -> Structured Data.
+        """
+        # We use OpenAI's structured output (JSON mode/tool calling) via Pydantic's response_format.
+        # For models that support it, we can pass the Pydantic model directly.
+        # If we are using an older model or vLLM, we might need to manually parse the JSON.
+
+        # Using the newer 'beta.chat.completions.parse' for Pydantic support
+        try:
+            completion = self.client.beta.chat.completions.parse(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": EXTRACTION_SYSTEM_PROMPT},
+                    {"role": "user", "content": filtered_text},
+                ],
+                response_format=ExtractionResult,
+            )
+            return completion.choices[0].message.parsed
+        except Exception as e:
+            print(f"Extraction Error: {e}")
+            # Return an empty ExtractionResult if parsing fails
+            return ExtractionResult()
+
+    def process_pipeline(self, raw_text: str) -> ExtractionResult:
+        """
+        Executes the two-stage pipeline: Raw Transcript -> Filtered Text -> Structured Data.
+        """
+        filtered_text = self.filter_transcript(raw_text)
+        if not filtered_text:
+            return ExtractionResult()
+
+        return self.extract_structured_data(filtered_text)

src/llm/prompts.py

@@ -0,0 +1,20 @@
+# System prompts for the LLM pipeline
+
+NOISE_FILTER_SYSTEM_PROMPT = """
+You are a D&D Game Master's assistant. Given a transcript, remove all out-of-character (OOC) chatter, logistical discussions (e.g., 'Where is my d20?'), and non-relevant noise.
+Output only the in-character dialogue and game-relevant events.
+Keep the original speakers' names if they are present in the transcript.
+Do not add any commentary or summaries. Just filter the text.
+"""
+
+EXTRACTION_SYSTEM_PROMPT = """
+You are a D&D session analyzer. Your goal is to extract structured data from a filtered transcript.
+Extract any changes to character states (HP, status effects, inventory) and any new lore facts (NPCs, locations, world-building).
+
+Guidelines:
+1. Lore: Identify any new information about the world, people, and places.
+2. Character State: Look for mentions of damage, healing, or items being gained or lost.
+3. Events: Note significant plot developments.
+
+Be precise. If no relevant information is found, return empty lists.
+"""