types

types

Data types for the diagnose phase.

Lightweight dataclasses used as return types by diagnostic tools and as internal data carriers. These are NOT pydantic models — they don't need validation or JSON schema generation.

See spec §5.2 for the tool return type rationale.

Classes

TraceMeta dataclass

TraceMeta(
    trace_id: str,
    query: str,
    agent: str,
    model: str,
    outcome: Optional[str],
    feedback: Optional[float],
    started_at: float,
)

Lightweight summary of a trace for browsing.

BenchmarkTask dataclass

BenchmarkTask(
    task_id: str,
    query: str,
    reference_answer: str,
    category: str = "chat",
)

One task from the personal benchmark.

StudentRun dataclass

StudentRun(
    task_id: str,
    output: str,
    score: float,
    trace_id: str,
    latency_seconds: float,
    tokens_used: int,
)

Result of re-executing the local student on a benchmark task.

TeacherRun dataclass

TeacherRun(
    task_id: str,
    output: str,
    reasoning: str,
    cost_usd: float,
    tokens_used: int,
)

Result of the teacher running itself on a benchmark task.

ComparisonResult dataclass

ComparisonResult(
    task_id: str,
    student_score: float,
    teacher_score: float,
    judge_reasoning: str,
)

Structured comparison between student and teacher outputs.

ToolMeta dataclass

ToolMeta(
    name: str,
    description: str,
    category: str,
    agents: list[str] = list(),
)

Metadata about a tool in the ToolRegistry.

DiagnosticTool dataclass

DiagnosticTool(
    name: str,
    description: str,
    parameters: dict[str, Any],
    fn: Callable[..., Any],
)

A tool exposed to the teacher in the diagnose phase.

Unlike BaseTool, these are not registered in ToolRegistry. They are lightweight wrappers: a name, description, JSON schema for parameters, and a callable that implements the tool.

Methods:

to_openai_function

to_openai_function() -> dict[str, Any]

Convert to OpenAI function-calling format.

Source code in src/diapason/learning/spec_search/diagnose/types.py

def to_openai_function(self) -> dict[str, Any]:
    """Convert to OpenAI function-calling format."""
    return {
        "type": "function",
        "function": {
            "name": self.name,
            "description": self.description,
            "parameters": self.parameters,
        },
    }

ToolCallRecord dataclass

ToolCallRecord(
    timestamp: datetime,
    tool: str,
    args: dict[str, Any],
    result: str,
    latency_ms: float,
    cost_usd: float,
)

One teacher tool call, persisted to the JSONL log.

Methods:

to_jsonl_dict

to_jsonl_dict() -> dict[str, Any]

Serialize to a JSON-safe dict for JSONL output.

Source code in src/diapason/learning/spec_search/diagnose/types.py

def to_jsonl_dict(self) -> dict[str, Any]:
    """Serialize to a JSON-safe dict for JSONL output."""
    return {
        "timestamp": self.timestamp.isoformat(),
        "tool": self.tool,
        "args": self.args,
        "result": self.result,
        "latency_ms": self.latency_ms,
        "cost_usd": self.cost_usd,
    }