docs/api/models.md

Models API Reference

This page documents the Pydantic models used throughout DeepCritical.

Evidence

Module: src.utils.models

Purpose: Represents evidence from search results.

Evidence Model start_line:33 end_line:44

Fields:

• citation: Citation information (title, URL, date, authors)
• content: Evidence text content
• relevance_score: Relevance score (0.0-1.0)
• metadata: Additional metadata dictionary

Citation

Module: src.utils.models

Purpose: Citation information for evidence.

Citation Model start_line:12 end_line:30

Fields:

• title: Article/trial title
• url: Source URL
• date: Publication date (optional)
• authors: List of authors (optional)

KnowledgeGapOutput

Module: src.utils.models

Purpose: Output from knowledge gap evaluation.

KnowledgeGapOutput Model start_line:494 end_line:504

Fields:

• research_complete: Boolean indicating if research is complete
• outstanding_gaps: List of remaining knowledge gaps

AgentSelectionPlan

Module: src.utils.models

Purpose: Plan for tool/agent selection.

AgentSelectionPlan Model start_line:521 end_line:526

Fields:

• tasks: List of agent tasks to execute

AgentTask

Module: src.utils.models

Purpose: Individual agent task.

AgentTask Model start_line:507 end_line:518

Fields:

• agent_name: Name of agent to use
• query: Task query
• context: Additional context dictionary

ReportDraft

Module: src.utils.models

Purpose: Draft structure for long-form reports.

ReportDraft Model start_line:538 end_line:545

Fields:

• title: Report title
• sections: List of report sections
• references: List of citations

ReportSection

Module: src.utils.models

Purpose: Individual section in a report draft.

ReportDraftSection Model start_line:529 end_line:535

Fields:

• title: Section title
• content: Section content
• order: Section order number

ParsedQuery

Module: src.utils.models

Purpose: Parsed and improved query.

ParsedQuery Model start_line:557 end_line:572

Fields:

• original_query: Original query string
• improved_query: Refined query string
• research_mode: Research mode ("iterative" or "deep")
• key_entities: List of key entities
• research_questions: List of research questions

Conversation

Module: src.utils.models

Purpose: Conversation history with iterations.

Conversation Model start_line:331 end_line:337

Fields:

• iterations: List of iteration data

IterationData

Module: src.utils.models

Purpose: Data for a single iteration.

IterationData Model start_line:315 end_line:328

Fields:

• iteration: Iteration number
• observations: Generated observations
• knowledge_gaps: Identified knowledge gaps
• tool_calls: Tool calls made
• findings: Findings from tools
• thoughts: Agent thoughts

AgentEvent

Module: src.utils.models

Purpose: Event emitted during research execution.

AgentEvent Model start_line:104 end_line:125

Fields:

• type: Event type (e.g., "started", "search_complete", "complete")
• iteration: Iteration number (optional)
• data: Event data dictionary

BudgetStatus

Module: src.utils.models

Purpose: Current budget status.

BudgetStatus Model start_line:15 end_line:25

Fields:

• tokens_used: Tokens used so far
• tokens_limit: Token limit
• time_elapsed_seconds: Elapsed time in seconds
• time_limit_seconds: Time limit in seconds
• iterations: Current iteration count
• iterations_limit: Iteration limit

See Also

• Architecture - Agents - How models are used
• Configuration - Model configuration