Skip to content

Agent tools

Local checks and compact result views used by the MCP server. These functions are also importable without the mcp extra. See the agent guide for the tool workflow.

Schema and capabilities

get_schema 

get_schema(definition: str | None = None) -> SchemaInfo

Return the local, read-only photonhub.schema/1 schema document.

capabilities 

capabilities() -> Capabilities

Return local, read-only photonhub.capabilities/1 solver facts.

Validation and planning

validate_spec 

validate_spec(
    spec: str | Path | dict | Simulation,
    device: str = "cpu",
    engine: bool = True,
) -> ValidationReport

Return local, read-only photonhub.validation/1 checks for a spec.

estimate 

estimate(
    spec: str | Path | dict | Simulation,
    cpu_mcells_per_s_low: float = 20.0,
    cpu_mcells_per_s_high: float = 300.0,
    device: str = "cpu",
) -> LocalEstimate

Return local, read-only photonhub.estimate/1 planning bounds.

Result inspection

result_summary 

result_summary(
    data_or_dir: RunResult | str | Path,
    data_checks: bool = True,
) -> ResultSummary

Return local, read-only photonhub.result_summary/1 findings and provenance.

convergence_report 

convergence_report(
    data_or_dir: RunResult | str | Path,
) -> ConvergenceSummary

Return local, read-only photonhub.convergence_report/1 evidence.

Output models

SchemaInfo pydantic-model

Bases: StrictModel

Local, read-only schema output for photonhub.schema/1.

Config:

  • extra: forbid
  • populate_by_name: True

Fields:

model_config class-attribute instance-attribute 

model_config = ConfigDict(
    extra="forbid", populate_by_name=True
)

contract pydantic-field 

contract: str = 'photonhub.schema/1'

schema_version pydantic-field 

schema_version: str

schema_major pydantic-field 

schema_major: int

schema_sha256 pydantic-field 

schema_sha256: str

definitions pydantic-field 

definitions: list[str]

definition pydantic-field 

definition: str | None

schema_ pydantic-field 

schema_: dict[str, Any]

Capabilities pydantic-model

Bases: StrictModel

Local, read-only capability output for photonhub.capabilities/1.

Fields:

contract pydantic-field 

contract: str = 'photonhub.capabilities/1'

sdk_version pydantic-field 

sdk_version: str

schema_version pydantic-field 

schema_version: str

schema_major pydantic-field 

schema_major: int

solver pydantic-field 

solver: SolverInfo

devices pydantic-field 

devices: list[DeviceInfo]

cpu_only_features pydantic-field 

cpu_only_features: list[CpuOnlyInfo]

pinned_features pydantic-field 

pinned_features: list[str]

safety pydantic-field 

safety: SafetyInfo

ValidationReport pydantic-model

Bases: StrictModel

Local validation output for photonhub.validation/1.

Fields:

contract pydantic-field 

contract: str = 'photonhub.validation/1'

ok pydantic-field 

ok: bool

authoritative pydantic-field 

authoritative: bool

device pydantic-field 

device: str

schema_version pydantic-field 

schema_version: str

input_sha256 pydantic-field 

input_sha256: str | None = None

input_sha256_basis pydantic-field 

input_sha256_basis: str | None = None

stages pydantic-field 

stages: dict[str, str]

issues pydantic-field 

issues: list[Issue]

counts pydantic-field 

counts: dict[str, int]

engine pydantic-field 

engine: EngineStatus

LocalEstimate pydantic-model

Bases: StrictModel

Local, read-only planning output for photonhub.estimate/1.

Fields:

contract pydantic-field 

contract: str = 'photonhub.estimate/1'

cells_per_axis pydantic-field 

cells_per_axis: tuple[int, int, int]

num_cells pydantic-field 

num_cells: int

num_steps pydantic-field 

num_steps: int

dt_s pydantic-field 

dt_s: float

cell_steps pydantic-field 

cell_steps: int

tcell_steps pydantic-field 

tcell_steps: float

memory_bytes pydantic-field 

memory_bytes: int

output_bytes pydantic-field 

output_bytes: int

cpu_seconds pydantic-field 

cpu_seconds: SecondsRange

assumptions pydantic-field 

assumptions: EstimateAssumptions

notes pydantic-field 

notes: list[str]

ResultSummary pydantic-model

Bases: StrictModel

Local, read-only result output for photonhub.result_summary/1.

Fields:

contract pydantic-field 

contract: str = 'photonhub.result_summary/1'

output_dir pydantic-field 

output_dir: str

input_sha256 pydantic-field 

input_sha256: str | None = None

input_sha256_source pydantic-field 

input_sha256_source: str | None = None

geometry_status pydantic-field 

geometry_status: str

manifest_version pydantic-field 

manifest_version: str | None = None

schema_version pydantic-field 

schema_version: str | None = None

solver pydantic-field 

solver: dict[str, Any]

device pydantic-field 

device: dict[str, Any]

run pydantic-field 

run: dict[str, Any]

grid pydantic-field 

grid: dict[str, Any]

monitors pydantic-field 

monitors: list[ResultMonitor]

issues pydantic-field 

issues: list[Issue]

counts pydantic-field 

counts: dict[str, int]

convergence pydantic-field 

convergence: ConvergenceLocation

ConvergenceSummary pydantic-model

Bases: StrictModel

Local, read-only output for photonhub.convergence_report/1.

Fields:

contract pydantic-field 

contract: str = 'photonhub.convergence_report/1'

found pydantic-field 

found: bool

path pydantic-field 

path: str | None = None

relation pydantic-field 

relation: str | None = None

format pydantic-field 

format: str | None = None

converged pydantic-field 

converged: bool | None = None

metric_name pydantic-field 

metric_name: str | None = None

stop_reason pydantic-field 

stop_reason: str | None = None

tol pydantic-field 

tol: float | None = None

patience pydantic-field 

patience: int | None = None

finest pydantic-field 

finest: float | None = None

drift_successive pydantic-field 

drift_successive: float | None = None

drift_total pydantic-field 

drift_total: float | None = None

total_cost_usd pydantic-field 

total_cost_usd: float | None = None

ladder pydantic-field 

ladder: list[dict[str, Any]] | None = None

keys pydantic-field 

keys: list[str] | None = None

message pydantic-field 

message: str | None = None

Issue pydantic-model

Bases: StrictModel

A stable finding from a local, read-only tool.

Fields:

id pydantic-field 

id: str

severity pydantic-field 

severity: str

path pydantic-field 

path: str | None = None

monitor pydantic-field 

monitor: str | None = None

message pydantic-field 

message: str

fix pydantic-field 

fix: str

detail pydantic-field 

detail: dict[str, Any] | None = None

SolverInfo pydantic-model

Bases: StrictModel

Solver facts from local, read-only capability probes.

Fields:

found pydantic-field 

found: bool

path pydantic-field 

path: str | None = None

version pydantic-field 

version: str | None = None

git_sha pydantic-field 

git_sha: str | None = None

gpu_available pydantic-field 

gpu_available: bool | None = None

gpu_platform pydantic-field 

gpu_platform: str | None = None

openmp pydantic-field 

openmp: bool | None = None

devices pydantic-field 

devices: list[Any] | None = None

features pydantic-field 

features: list[str] | None = None

feature_drift pydantic-field 

feature_drift: list[str] | None = None

error pydantic-field 

error: str | None = None

DeviceInfo pydantic-model

Bases: StrictModel

Availability of one local device selector.

Fields:

selector pydantic-field 

selector: str

available pydantic-field 

available: bool

note pydantic-field 

note: str

CpuOnlyInfo pydantic-model

Bases: StrictModel

A feature restricted to the local CPU solver.

Fields:

name pydantic-field 

name: str

section pydantic-field 

section: str

message pydantic-field 

message: str

SafetyInfo pydantic-model

Bases: StrictModel

Side effect flags for a local, read-only capability report.

Fields:

spends_money pydantic-field 

spends_money: bool = False

network pydantic-field 

network: bool = False

cloud_submission pydantic-field 

cloud_submission: bool = False

EngineStatus pydantic-model

Bases: StrictModel

Compact outcome of a local solver validation probe.

Fields:

ran pydantic-field 

ran: bool = False

solver pydantic-field 

solver: str | None = None

result pydantic-field 

result: Any = None

SecondsRange pydantic-model

Bases: StrictModel

Estimated local CPU time bounds in seconds.

Fields:

low pydantic-field 

low: float

high pydantic-field 

high: float

EstimateAssumptions pydantic-model

Bases: StrictModel

Throughput assumptions for a local, read-only estimate.

Fields:

cpu_mcells_per_s pydantic-field 

cpu_mcells_per_s: list[float]

basis pydantic-field 

basis: str

ResultMonitor pydantic-model

Bases: StrictModel

One recorded monitor in a local result summary.

Fields:

name pydantic-field 

name: str

type pydantic-field 

type: str | None = None

kind pydantic-field 

kind: str | None = None

shape pydantic-field 

shape: list[int] | None = None

components pydantic-field 

components: list[str] | None = None

n_freqs pydantic-field 

n_freqs: int | None = None

axis pydantic-field 

axis: str | None = None

ConvergenceLocation pydantic-model

Bases: StrictModel

Location of a report saved beside the local result.

Fields:

found pydantic-field 

found: bool

path pydantic-field 

path: str | None = None