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.

Functions

to_openai_function

to_openai_function() -> dict[str, Any]

Convert to OpenAI function-calling format.

Source code in src/openjarvis/learning/distillation/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.

Functions

to_jsonl_dict

to_jsonl_dict() -> dict[str, Any]

Serialize to a JSON-safe dict for JSONL output.

Source code in src/openjarvis/learning/distillation/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,
    }