AI Subsystem Quickstart

Overview

Lexigram's AI stack is modular: 15+ lexigram-ai-* packages wired through AIModule. All follow contract-first DI — inject *Protocol, swap backends via config. See docs/guides/ai-*.md for deep dives.

LLM Client

from lexigram.contracts.ai.llm import LLMClientProtocol
from lexigram.contracts.ai.llm import ChatMessage, Role

class MyService:
    def __init__(self, llm: LLMClientProtocol):
        self.llm = llm

    async def summarize(self, text: str) -> Result[str, AIError]:
        messages = [ChatMessage(role=Role.USER, content=text)]
        result = await self.llm.complete(messages)
        return result.map_sync(lambda r: r.content)

RAG Pipeline

from lexigram.contracts.ai.rag import RAGPipelineProtocol, RAGContext

class QAService:
    def __init__(self, rag: RAGPipelineProtocol):
        self.rag = rag

    async def answer(self, question: str) -> Result[str, AIError]:
        result = await self.rag.execute(RAGContext(query=question))
        return result.map_sync(lambda r: r.answer)

Agents

from lexigram.contracts.ai.agents import AgentExecutorProtocol, ToolProtocol

class SearchTool(ToolProtocol):
    @property
    def name(self) -> str:
        return "search"

    @property
    def description(self) -> str:
        return "Search the docs"

    @property
    def parameters_schema(self) -> dict:
        return {"type": "object", "properties": {"query": {"type": "string"}}}

    async def execute(self, **kwargs) -> str:
        return f"Results for: {kwargs.get('query', '')}"

executor = await container.resolve(AgentExecutorProtocol)
result = await executor.run(agent, "Find docs about caching")  # run(agent, message, ...)

Configuration

LLM settings live in the top-level ai_llm section (not under ai:). providers is an ordered list — cascade order, first = highest priority:

Hosted (OpenAI, Anthropic, …):

ai_llm:
  providers:
    - name: primary
      provider: openai
      model: gpt-4-turbo
      api_key: ${OPENAI_API_KEY}
      temperature: 0.7
      max_tokens: 2048
      thinking:                     # For reasoning models
        budget_tokens: 4096

Local — any OpenAI-compatible server (Ollama, LM Studio, vLLM, llama.cpp):

ai_llm:
  providers:
    - name: local
      provider: openai_compatible
      model: llama3.2
      api_base: http://localhost:11434/v1   # Ollama default; swap for LM Studio / vLLM
      api_key: ollama                       # Local servers usually ignore the value

Shared knobs go under defaults: (temperature, max_tokens).

Module Registration

from lexigram.ai import AIModule

async with Application.boot(modules=[
    AIModule.configure(ai_config),
]) as app:
    llm = await app.container.resolve(LLMClientProtocol)

Testing

@module(imports=[AIModule.stub()])  # No-op AI
class TestModule(Module): pass

Quick Reference

Common Mistakes

• Importing across AI sub-packages — use contracts + DI, never lexigram-ai-agents → lexigram-ai-llm
• Reasoning models: thinking is off unless a ThinkingConfig is supplied; set ThinkingConfig(suppress=True) to strip thinking tokens from responses
• Not calling result.map() on LLM responses — forget Result unwrapping discipline
• Missing LLM fallback providers — single-provider setup has no resilience
• Using AIModule.stub() when testing — otherwise tests call real APIs