Tool contract spec

Request Schema

Standard request fields for all tool calls. Each tool extends with its own parameters.

ToolRequest {
  design_ref: DesignRef        // Design reference: "design_name@tech_lib"
  intent_ref?: IntentRef       // Intent reference—problem the Agent solves
  scenario_ref?: ScenarioRef   // Scenario reference—current flow stage
  effort?: str                 // Compute effort: "quick" | "standard" | "exhaustive"
  budget?: CostBudget          // Cost budget constraint
  snap_ref?: SnapshotRef       // Target snapshot—defaults to main head
  dirty_hint?: DirtySetRef     // DirtySet reference—dirty region for incremental compute
}

// Extended example: iPL.place request
PlaceRequest extends ToolRequest {
  congestion_weight?: f64      // Congestion optimization weight (0.0~1.0)
  timing_weight?: f64          // Timing optimization weight (0.0~1.0)
  density_target?: f64         // Target density (0.0~1.0)
  max_iterations?: int         // Maximum iterations
}

Result Schema

Standard result fields for all tool calls. Ensures Agents receive structured, comparable returns.

ToolResult {
  value: Any                    // Tool-specific return value
  uncertainty?: f64             // Result uncertainty (0.0~1.0), 0 = deterministic
  coverage?: f64                // Verification coverage (0.0~1.0)
  provenance?: Provenance       // Result provenance
  warnings?: []str              // Non-fatal warnings
  elapsed_ms: int               // Tool execution time (ms)
}

Provenance {
  tool_name: str               // Tool that produced this result
  tool_version: str            // Tool version
  input_snap: SnapshotRef      // Input snapshot
  input_params_hash: str       // Input parameter hash (for cache comparison)
  computed_at: Timestamp       // Computation timestamp
}

// Extended example: iSTA.analyze result
STAResult extends ToolResult {
  value: TimingReport {
    wns: f64                   // Worst Negative Slack (ns)
    tns: f64                   // Total Negative Slack (ns)
    critical_paths: []Path     // Critical path list
    clock_domains: {}ClockSummary // Timing summary per clock domain
  }
  uncertainty: 0.15            // 15% uncertainty (STA model estimate)
  coverage: 0.98               // 98% of timing paths covered
}

Proposal / Delta / Certificate

Core types for Agent proposals, design changes, and verification certificates.

Proposal

Proposal {
  id: str                      // Unique proposal ID
  intent_ref: IntentRef        // Intent—optimization goal the Agent targets
  expected_delta: DesignDelta  // Expected design change
  expected_metrics: {}MetricGoal // Expected metric change, e.g. {"hpwl": "-5%"}
  rationale?: str              // Agent decision rationale (natural language)
  parent_snap: SnapshotRef     // Snapshot this proposal is based on
  confidence?: f64             // Agent confidence in this proposal (0.0~1.0)
}

DesignDelta

DesignDelta {
  moved_cells: []CellMove {
    cell_id: StableId
    from: Position
    to: Position
  }
  resized_cells: []CellResize
  new_nets: []NetChange
  timing_changes: []TimingDelta
  drc_changes: []DRCDelta
  summary: DeltaSummary {
    cells_affected: int
    nets_affected: int
    area_delta: f64           // Total area change (um^2)
  }
}

Certificate

Certificate {
  id: str                      // Unique certificate ID
  proposal_id: str             // Verified proposal
  gate_result: GateJudgment    // Gate judgment result
  pareto_position: ParetoRank  // Pareto frontier position
  regret: f64                  // Regret vs best candidate
  signed_by: str               // Issuer: "Evaluation/v0.2.0"
  signed_at: Timestamp
}

Tool capability declarations

Every tool must declare its capabilities—Agents can judge fit before picking tools.

ToolCapability {
  tool_name: str               // Tool name, e.g. "iPL.place"
  version: str                 // Tool version
  supported_scenarios: []str   // Supported scenarios: ["placement", "floorplan", ...]
  fidelity_levels: []str       // Fidelity levels: ["quick", "standard", "exhaustive"]
  input_constraints: {         // Input constraints
    requires_snapshot: bool
    requires_dirty_set: bool
    max_design_cells?: int     // Maximum supported cell count
    supported_techs?: []str    // Supported tech libs, null = all
  }
  output_schema: Schema        // Output JSON Schema
  known_limitations: []str     // Known limitations (natural language)
  performance_profile: {       // Performance profile
    typical_latency_ms: int
    peak_memory_mb: int
    scaling: str               // "linear" | "nlogn" | "quadratic"
  }
}

Contract versioning

Tool contracts follow semantic versioning—Agents judge compatibility from version numbers.

# Semantic versioning for tool contracts: MAJOR.MINOR.PATCH

# MAJOR (X.0.0): Breaking changes
#   - Removing a field from result
#   - Changing a field type
#   - Renaming a required parameter

# MINOR (0.X.0): Backward-compatible additions
#   - Adding a new optional parameter
#   - Adding a new field to result
#   - Adding a new fidelity level

# PATCH (0.0.X): Behavior-only changes
#   - Bug fixes that don't change the schema
#   - Performance improvements
#   - Documentation updates

# Agent compatibility check
agent_depends_on: "iPL.place >= 1.2.0, < 2.0.0"
platform_provides: "iPL.place @ 1.3.1"
# → Compatible: 1.2.0 <= 1.3.1 < 2.0.0 ✓

# Contract negotiation at connection time
client = AgentClient(required_contracts={
    "iDB": ">=0.8.0",
    "iPL": ">=1.2.0",
    "iSTA": ">=1.0.0",
})
client.connect()  # Fails if platform cannot satisfy requirements

Contract spec · Typed API contracts