State Schema — LangGraph

Contrato operacional do estado partilhado entre agentes. Para uso com LangGraph (TypedDict ou Pydantic).

---

Índice

1. Generate Content State
2. Chat/QA State
3. Evaluate State
4. Ficheiro state.py (proposta)

---

Generate Content State

Estado partilhado entre Router → Content Planner → Content Writer → Question Generator.

from typing import TypedDict, Optional
from uuid import UUID

class GenerateContentState(TypedDict, total=False):
    # Input
    topic: str
    project_id: UUID
    user_id: UUID
    job_id: UUID
    
    # Content Planner output
    planned_sections: list[dict]  # [{title, subsections: [...]}]
    missing_topics: list[str]
    confidence: float
    
    # Content Writer state (loop)
    current_section_index: int
    current_section: dict
    retrieved_chunks: list[dict]  # [{content, source, metadata}]
    draft_content: str  # Markdown acumulado
    citations: list[dict]  # [{source, excerpt, chunk_id}]
    
    # Question Generator input
    full_document: str
    document_id: Optional[UUID]
    
    # Output
    questions: list[dict]
    status: str  # planning, writing, questions, done, error
    error: Optional[str]

Fluxo de campos

Merge no LangGraph

Cada nó devolve apenas os campos que altera. LangGraph faz merge automático com Reducer ou Annotation (add para listas).

---

Chat/QA State

Estado para RAG QA Agent (e Router quando encaminha).

class ChatState(TypedDict, total=False):
    project_id: UUID
    user_id: UUID
    session_id: Optional[UUID]
    
    message: str
    history: list[dict]  # [{role, content}]
    
    # Router
    intent: str
    intent_confidence: float
    
    # RAG QA
    retrieved_chunks: list[dict]
    response: str
    citations: list[dict]
    
    # Trace (para persistência)
    trace_id: Optional[str]  # LangSmith run ID

---

Evaluate State

class EvaluateState(TypedDict, total=False):
    question_id: UUID
    user_answer: str
    question: str
    solution: str
    material_chunks: list[dict]
    
    # Evaluator output
    rule_score: int
    llm_score: int
    score: int
    accuracy: int
    completeness: int
    clarity: int
    feedback: str
    corrections: list[str]

---

Ficheiro state.py (proposta)

Estrutura no código:

api/
├── app/
│   ├── agents/
│   │   ├── state.py      # TypedDicts / Pydantic
│   │   ├── graph.py      # LangGraph definition
│   │   ├── nodes/
│   │   │   ├── router.py
│   │   │   ├── planner.py
│   │   │   ├── writer.py
│   │   │   └── ...
│   │   └── edges.py

state.py:

# app/agents/state.py
from typing import TypedDict, Optional, Annotated
from uuid import UUID
from langgraph.graph.message import add_messages

class GenerateContentState(TypedDict, total=False):
    topic: str
    project_id: str
    user_id: str
    job_id: str
    planned_sections: list
    missing_topics: list
    confidence: float
    current_section_index: int
    current_section: dict
    retrieved_chunks: list
    draft_content: str
    citations: list
    full_document: str
    document_id: Optional[str]
    questions: list
    status: str
    error: Optional[str]

Ver AGENTS.md para fluxos.