LLM Provider Integration
Relevant source files
The following files were used as context for generating this wiki page:
LLM Provider Integration is a core component of the narrative-ai service, responsible for driving the dynamic storytelling capabilities of the MCP Games ecosystem. This system leverages Large Language Models (LLMs) to generate context-aware narratives, character interactions, and branching plotlines by injecting real-world data retrieved via the Model Context Protocol (MCP).
The integration provides a multi-provider framework, primarily supporting OpenAI and Anthropic models, to ensure narrative consistency and high-quality generation. It acts as the bridge between structured game state data and the generative capabilities of modern AI, allowing the story to adapt based on user preferences and external data sources like GitHub or Linear.
Sources: apps/narrative-ai/README.md:3-10, README.md:36-41
Architecture and Service Flow
The LLM integration is hosted within a FastAPI-based microservice. It consumes data from the mcp-connector and story-engine to form prompts that are processed by LLM providers.
The diagram shows the flow of information from the user-facing engine through the AI service to the external LLM providers.
Sources: README.md:15-25, apps/narrative-ai/README.md:14-22
Core Generation Components
The system breaks down narrative generation into specific functional areas to maintain control over the story structure and token usage.
Narrative Generation Requests
The system uses structured data models to communicate with the AI service. These models ensure that the LLM receives the necessary context, including story history and MCP-derived data.
| Field | Type | Description |
|---|---|---|
storyId | string | Unique identifier for the current story instance. |
sceneTemplate | string | The base template used for the current scene. |
userContext | Record<string, unknown> | Data specific to the user (e.g., preferences). |
mcpData | Record<string, unknown> | Context retrieved from MCP servers (GitHub, Linear, etc.). |
previousChoices | string[] | A history of choices made by the player to ensure consistency. |
Sources: packages/shared-types/src/index.ts:161-167
API Endpoints
The narrative-ai service exposes specific endpoints for different stages of the LLM generation process:
- Scene Generation:
POST /api/generate/scene- Generates the main narrative text for a scene. - Choice Generation:
POST /api/generate/choices- Creates context-aware options for the player. - Consequence Generation:
POST /api/generate/consequence- Processes the result of a specific choice.
Sources: apps/narrative-ai/README.md:27-31, apps/narrative-ai/main.py:46-75
Configuration and Environment
The integration is configured via environment variables, allowing for flexible switching between providers and models.
# apps/narrative-ai/main.py:8-10
load_dotenv()
# Default model configuration used in metadata
# Sources: [apps/narrative-ai/README.md:40-42]
DEFAULT_MODEL = os.getenv("DEFAULT_MODEL", "gpt-4-turbo-preview")
Provider Environment Variables
| Variable | Description |
|---|---|
OPENAI_API_KEY | API key for OpenAI services (GPT-4, etc.). |
ANTHROPIC_API_KEY | API key for Anthropic services (Claude, etc.). |
DEFAULT_MODEL | The specific model version to target for generations. |
Sources: apps/narrative-ai/README.md:38-42
Data Models and Responses
The LLM output is wrapped in a response object that includes both the generated text and technical metadata for monitoring performance and cost.
The class diagram represents the structure of the data returned by the LLM integration to the calling services.
Sources: apps/narrative-ai/main.py:34-38, packages/shared-types/src/index.ts:173-177
Implementation Details
The implementation utilizes LangChain and the OpenAI SDK for Python to manage the interaction with LLMs. The service is built with FastAPI to provide a high-performance interface for the cyoa-engine.
Scene Generation Logic
When a scene is generated, the system incorporates the user_context and previous_choice into the prompt. The response includes the generated narrative text and metadata regarding token usage.
@app.post("/api/generate/scene", response_model=NarrativeResponse)
async def generate_scene(request: GenerateSceneRequest):
# Implementation pending logic for LLM-based scene generation
return NarrativeResponse(
text="Scene generation endpoint - implementation pending",
metadata={
"story_id": request.story_id,
"model": "gpt-4-turbo-preview",
"tokens_used": 0
}
)
Sources: apps/narrative-ai/main.py:46-56, README.md:41
Conclusion
The LLM Provider Integration is the intelligence layer of the MCP Games monorepo. By abstracting provider-specific logic into the narrative-ai service and utilizing shared types for consistent data exchange, the system enables highly personalized and dynamic Choose Your Own Adventure experiences. Its ability to consume MCP-derived context allows the AI to generate stories that are uniquely tailored to a user's real-world professional or personal data.