OSSS.ai.orchestration.state_schemas

OSSS.ai.orchestration.state_schemas

LangGraph state schemas for OSSS agents.

This module provides TypedDict definitions for type-safe state management in LangGraph StateGraph execution. Each agent output is strictly typed to ensure consistency and enable proper validation.

Design Principles: - Type safety through TypedDict definitions - Clear separation of agent outputs - Validation helpers for state integrity - Comprehensive documentation for maintainability

LangGraphState = OSSSState module-attribute

Alias for OSSSState to improve code readability.

AgentStateUnion = Union[RefinerState, CriticState, HistorianState, SynthesisState] module-attribute

Union type for any agent output schema.

RefinerState

Bases: TypedDict

Output schema for the RefinerAgent.

The RefinerAgent transforms raw user queries into structured, clarified prompts for downstream processing.

refined_question instance-attribute

The clarified and structured version of the original query.

topics instance-attribute

List of identified topics and themes in the query.

confidence instance-attribute

Confidence score (0.0-1.0) in the refinement quality.

processing_notes instance-attribute

Optional notes about the refinement process.

timestamp instance-attribute

ISO timestamp when refinement was completed.

DataQueryState

Bases: TypedDict

Output schema for the DataQueryAgent.

This remains for backward compatibility with single data_query usage. Option A prefers OSSSState.data_query_results keyed by node-id.

CriticState

Bases: TypedDict

Output schema for the CriticAgent.

The CriticAgent provides analytical critique and evaluation of the refined query and suggests improvements.

critique instance-attribute

Detailed critique of the refined question and approach.

suggestions instance-attribute

List of specific improvement suggestions.

severity instance-attribute

Severity level: 'low', 'medium', 'high', 'critical'.

strengths instance-attribute

Identified strengths in the current approach.

weaknesses instance-attribute

Identified weaknesses or gaps in the approach.

confidence instance-attribute

Confidence score (0.0-1.0) in the critique accuracy.

timestamp instance-attribute

ISO timestamp when critique was completed.

HistorianState

Bases: TypedDict

Output schema for the HistorianAgent.

The HistorianAgent retrieves and analyzes historical context using intelligent search and LLM-powered relevance analysis.

historical_summary instance-attribute

Synthesized historical context relevant to the current query.

retrieved_notes instance-attribute

List of filepaths for notes that were retrieved and used.

search_results_count instance-attribute

Number of search results found before filtering.

filtered_results_count instance-attribute

Number of results after relevance filtering.

search_strategy instance-attribute

Type of search strategy used (e.g., 'hybrid', 'tag-based', 'keyword').

topics_found instance-attribute

List of topics identified in the retrieved historical content.

confidence instance-attribute

Confidence score (0.0-1.0) in the historical context relevance.

llm_analysis_used instance-attribute

Whether LLM was used for relevance analysis and synthesis.

metadata instance-attribute

Additional metadata about the historical search process.

timestamp instance-attribute

ISO timestamp when historical analysis was completed.

SynthesisState

Bases: TypedDict

Output schema for the SynthesisAgent.

The SynthesisAgent generates final synthesis from multiple agent outputs, creating coherent and comprehensive analysis.

final_analysis instance-attribute

Comprehensive final analysis integrating all inputs.

key_insights instance-attribute

List of key insights derived from the analysis.

sources_used instance-attribute

List of source agents/outputs used in synthesis.

themes_identified instance-attribute

Major themes identified across all inputs.

conflicts_resolved instance-attribute

Number of conflicts resolved during synthesis.

confidence instance-attribute

Confidence score (0.0-1.0) in the synthesis quality.

metadata instance-attribute

Additional metadata about the synthesis process.

timestamp instance-attribute

ISO timestamp when synthesis was completed.

ExecutionMetadata

Bases: TypedDict

Metadata about the LangGraph execution process.

execution_id instance-attribute

Unique identifier for this execution.

correlation_id instance-attribute

Correlation ID for event tracking and WebSocket filtering.

start_time instance-attribute

ISO timestamp when execution started.

orchestrator_type instance-attribute

Type of orchestrator: 'langgraph-real'.

agents_requested instance-attribute

List of agents requested for execution.

execution_mode instance-attribute

Execution mode: 'langgraph-real'.

phase instance-attribute

Implementation phase label (e.g., 'phase2_1').

agent_outputs instance-attribute

Per-agent execution outputs and metadata.

FinalState

Bases: TypedDict

Output schema for the FinalAgent.

The FinalAgent produces the user-facing answer, optionally using RAG and other agent outputs.

final_answer instance-attribute

User-facing final answer text.

used_rag instance-attribute

Whether RAG context actually influenced this answer.

rag_excerpt instance-attribute

Optional excerpt of RAG context surfaced in the answer.

sources_used instance-attribute

List of sources or agents referenced (e.g. ['refiner', 'historian']).

timestamp instance-attribute

ISO timestamp when the final answer was produced.

ExecutionConfig

Bases: TypedDict

Configuration for orchestration execution.

This captures relatively static knobs that influence how the workflow runs (graph pattern, RAG settings, etc.).

graph_pattern instance-attribute

Name of the graph pattern to use (e.g. 'standard', 'data_query').

rag instance-attribute

RAG-related configuration (index, filters, limits, etc.).

timeout_seconds instance-attribute

Overall timeout for the workflow, if enforced at orchestrator level.

use_rag instance-attribute

Whether RAG should be used for this execution.

use_llm_intent instance-attribute

Whether LLM-based intent classification is enabled.

parallel_execution instance-attribute

Whether orchestrator is allowed to run nodes in parallel.

top_k instance-attribute

Default top_k for RAG / search integrations.

workflow_id instance-attribute

Workflow id, if the caller pins this execution to a specific workflow.

ExecutionState

Bases: TypedDict

Dynamic orchestration state managed by the orchestrator.

This lives inside OSSSState.execution_state and is the single source of truth for orchestration-related flags, RAG state, and routing decisions.

execution_config instance-attribute

Primary execution configuration (graph pattern, RAG config, etc.).

config instance-attribute

Deprecated alias; prefer execution_config.

rag_enabled instance-attribute

Whether RAG was actually enabled (after applying config + policy).

rag_context instance-attribute

Full RAG context text accumulated for this execution.

rag_snippet instance-attribute

Short RAG snippet used for preview / UX.

rag_hits instance-attribute

Raw RAG search hits / documents.

rag_meta instance-attribute

Metadata about RAG (index, provider, embedding model, top_k, etc.).

rag_error instance-attribute

If RAG prefetch failed, error message goes here.

routing_decision instance-attribute

Opaque routing decision payload (agents to run, topics, etc.).

agents_to_run instance-attribute

Concrete list of agents selected for this execution.

graph_pattern instance-attribute

Resolved graph pattern (may mirror config.graph_pattern or be derived).

planned_agents instance-attribute

Authoritative list of agent node names used to build the graph.

agent_output_meta instance-attribute

Per-agent metadata (query_profile, timing, etc.) populated by agents.

route instance-attribute

Resolved route key (e.g. 'data_query' or 'refiner').

route_key instance-attribute

High-level route type (e.g. 'action', 'informational').

route_reason instance-attribute

Optional free-form explanation of why this route was chosen.

route_locked instance-attribute

Whether routing was pre-locked by the caller (no override).

user_question instance-attribute

Question the system is currently answering (may differ from original raw query).

original_query instance-attribute

Exact original query string preserved for logging/debugging.

query instance-attribute

Raw query text stored at execution_state level (if caller wants it here).

raw_query instance-attribute

Alternative field for raw query strings (for compatibility with callers).

task_classification instance-attribute

Classifier-level task classification (intent + confidence).

cognitive_classification instance-attribute

Classifier-level cognitive/domain classification.

classifier_profile instance-attribute

Full classifier profile (intent, domain, topics, etc.).

classifier instance-attribute

Thin classifier view for routing.

refiner_full_text instance-attribute

Full markdown/text output from the refiner agent.

refiner_snippet instance-attribute

Short refiner snippet for UI / final agent conditioning.

refiner_topics instance-attribute

Topics pulled directly from the refiner output, if any.

refiner_confidence instance-attribute

Refiner-level confidence in its topic analysis (if present).

effective_queries instance-attribute

Per-stage effective query strings (user/refiner/data_query/etc.).

data_query_result instance-attribute

Canonical result payload from the latest data_query node.

data_query_node_id instance-attribute

Node id of the data_query result we surfaced as data_query_result.

wizard instance-attribute

Optional wizard / CRUD workflow state (used by data_query pattern).

intent instance-attribute

Top-level intent label if classification has already run (e.g. 'action', 'informational').

structured_outputs instance-attribute

Structured outputs attached at the orchestration layer (mirrors top-level OSSSState.structured_outputs).

agent_output_index instance-attribute

Index of agent outputs as returned to external callers.

conversation_id instance-attribute

Conversation/thread id used by the caller.

orchestrator_type instance-attribute

Type of orchestrator: 'langgraph-real'.

orchestrator_span instance-attribute

Tracing span id for the orchestrator.

execution_id instance-attribute

Execution id mirrored from execution_metadata.

correlation_id instance-attribute

Correlation id mirrored from execution_metadata / caller.

thread_id instance-attribute

Thread id from OSSSContext.

agents_requested instance-attribute

Agents originally requested by the caller / planner.

execution_time_ms instance-attribute

Total execution time for the workflow in milliseconds.

langgraph_execution instance-attribute

Whether this run used LangGraph (vs a legacy orchestrator).

checkpoints_enabled instance-attribute

Whether LangGraph checkpoints were enabled.

successful_agents_count instance-attribute

Count of successful agents for metrics/telemetry.

failed_agents_count instance-attribute

Count of failed agents for metrics/telemetry.

errors_count instance-attribute

Count of errors encountered during this execution.

correlation_context instance-attribute

Full correlation context (workflow id, parent span, ad-hoc metadata).

raw_request_config instance-attribute

Raw, unnormalized request config as provided to the orchestrator.

workflow_result instance-attribute

Full workflow result envelope (as returned by LangGraph orchestrator).

OSSSState

Bases: TypedDict

Master state schema for OSSS LangGraph execution.

This represents the complete state that flows through the LangGraph StateGraph during execution. Each agent contributes its typed output to this shared state.

Orchestration-specific state (RAG, routing, etc.) is stored in the nested ExecutionState structure under execution_state.

query instance-attribute

The original user query to process.

refiner instance-attribute

RefinerState from the RefinerAgent (populated after refiner node).

critic instance-attribute

Output from the CriticAgent (populated after critic node).

historian instance-attribute

Output from the HistorianAgent (populated after historian node).

synthesis instance-attribute

Output from the SynthesisAgent (populated after synthesis node).

data_query instance-attribute

Legacy data query output (single). Prefer data_query_results for Option A.

planned_data_query_nodes instance-attribute

Ordered list of data_query node IDs planned by routing (e.g., ['data_query:teachers']).

completed_data_query_nodes instance-attribute

List of data_query node IDs that completed (supports concurrent appends via reducer).

data_query_results instance-attribute

Aggregated per-node results keyed by node ID (supports concurrent merges via reducer).

execution_metadata instance-attribute

Metadata about the current execution.

errors instance-attribute

List of errors encountered during execution.

successful_agents instance-attribute

List of agents that completed successfully.

failed_agents instance-attribute

List of agents that failed during execution.

structured_outputs instance-attribute

Full Pydantic model outputs from agents for database/API persistence.

final instance-attribute

Output from the FinalAgent (user-facing answer).

execution_state instance-attribute

Nested, strongly-typed orchestration state (RAG, routing, etc.).

OSSSContext dataclass

Context schema for OSSS LangGraph execution.

This context is passed to all nodes during graph execution, providing thread-scoped information and configuration.

merge_structured_outputs(left, right)

Merge two structured output dicts for concurrent LangGraph updates.

This reducer allows multiple agents (e.g., critic and historian) to write to structured_outputs in parallel without conflicts. The right dict values override left dict values for matching keys.

create_initial_state(query, execution_id, correlation_id=None)

Create the initial LangGraph state for a new execution.

This function initializes: - Core query and metadata - Empty agent outputs - Empty data_query planning structures - Strongly-typed ExecutionState with default config & RAG state

validate_state_integrity(state)

Validate LangGraph state integrity.

Note: This validates the core invariant fields and any agent outputs that are present. It does not require optional/route-dependent fields (e.g., critic/historian/data_query).

get_agent_state(state, agent_name)

Get typed agent state from state.

set_agent_state(state, agent_name, output)

Set typed agent state in state.

Note: This function preserves reducer semantics by only appending a single agent_name to successful_agents per call.

record_agent_error(state, agent_name, error)

Record agent execution error in state.

Handles both complete and partial state objects gracefully.