OSSS.ai.agents.models

OSSS.ai.agents.models

Pydantic models for structured agent outputs.

This module defines the data structures that agents return when using Pydantic AI for structured response validation. These models ensure consistent data shapes in the execution_metadata JSONB field while maintaining agent swapping flexibility.

ConfidenceLevel

Bases: str, Enum

Confidence levels for agent outputs.

BiasType

Bases: str, Enum

Types of biases that can be identified by the Critic agent.

BiasDetail

Bases: BaseModel

Structured detail about a specific bias identified by the Critic agent.

This model replaces the Dict[str, str] bias_details field to ensure compatibility with OpenAI's structured output API, which requires all fields to have predefined schemas (additionalProperties: false).

ProcessingMode

Bases: str, Enum

Processing modes for agents.

BaseAgentOutput

Bases: BaseModel

Base class for all agent outputs with common metadata.

RefinerOutput

Bases: BaseAgentOutput

Structured output from the Refiner agent.

CriticOutput

Bases: BaseAgentOutput

Structured output from the Critic agent.

validate_critique_content_only(v) classmethod

Prevent content pollution in critique summary.

Based on LangChain article validation patterns.

validate_analysis_items(v) classmethod

Validate analysis items contain content only, not process descriptions.

validate_issues_consistency()

Ensure issues_detected count is within reasonable bounds.

NOTE: We do NOT enforce strict matching with actual array lengths because: 1. LLM counts semantically (conceptual issues) vs mechanically (array items) 2. Some issues may be mentioned in summary but not detailed 3. Some array items may combine multiple related issues

We only validate the count is reasonable (0-100 range).

HistoricalReference

Bases: BaseModel

Reference to a historical document or context.

HistorianOutput

Bases: BaseAgentOutput

Structured output from the Historian agent.

validate_historical_content_only(v) classmethod

Prevent content pollution in historical synthesis.

Based on LangChain article validation patterns for content purity.

validate_historical_items(v) classmethod

Validate historical items contain insights only, not process descriptions.

validate_source_counts()

Ensure source counts are consistent.

SynthesisTheme

Bases: BaseModel

A synthesized theme with supporting evidence.

SynthesisOutput

Bases: BaseAgentOutput

Structured output from the Synthesis agent.

validate_synthesis_content_only(v) classmethod

Prevent content pollution in final synthesis.

Based on LangChain article validation patterns for content purity.

validate_synthesis_items(v) classmethod

Validate synthesis items contain content only, not process descriptions.

validate_topics_format(v) classmethod

Validate and normalize topic formats.

Character limit increased from 50 → 100 chars (2025-01-27) to accommodate LLM natural language topic extraction. Topics exceeding 100 chars are truncated rather than rejected to prevent validation retry cascades.

validate_synthesis_consistency()

Ensure synthesis consistency and completeness.

Updates

• If word_count is missing, compute it from final_synthesis.
• If word_count is present, validate with tolerance.
• Do NOT require contributing_agents to be non-empty (Option A / skips).
• If contributing_agents is provided, validate names.

DatabaseExecutionMetadata

Bases: BaseModel

Execution metadata for JSONB storage.

This version is oriented around the refiner / data_query / final pattern. Critic & synthesis are not required for persistence; arbitrary agents can still write generic dict payloads into agent_outputs.

create_agent_output(agent_name, **kwargs)

Factory function to create the appropriate agent output based on agent name.

Parameters:

Name	Type	Description	Default
agent_name	str	Name of the agent ("refiner", "critic", "historian", "synthesis")	required
**kwargs	Any	Agent-specific output data	{}

Returns:

Type	Description
AgentStructuredOutput	Appropriate agent output model instance

Raises:

Type	Description
ValueError	If agent_name is not recognized