API reference

Python SDK

Python SDK is the main entry for data scientists and AI engineers. Full IDE autocomplete for all types.

AgentClient

Entry class for Agents accessing iEDA Platform. Manages session, connection, and configuration.

class AgentClient(
    host: str = "localhost",
    port: int = 9090,
    protocol: str = "python",
    tracing: bool = False,
    timeout_ms: int = 30000,
)
# host:         iEDA Platform service address
# port:         Interface gateway port
# protocol:     "python" | "mcp" | "tcl"
# tracing:      Enable performance tracing
# timeout_ms:   Default tool call timeout (ms)

# Methods
def connect() -> None
def disconnect() -> None
def load_design(name: str, tech: str) -> DesignHandle
def call(tool: str, **kwargs) -> ToolResult
def list_tools(filter: Optional[str] = None) -> List[ToolDef]
def snapshot(design: DesignHandle, label: Optional[str] = None) -> SnapshotRef

load_design

def load_design(
    name: str,                   # Design name, e.g. "aes_core"
    tech: str,                   # Tech library, e.g. "sky130", "nangate45"
    config: Optional[DesignConfig] = None,
) -> DesignHandle

# Example
client = AgentClient()
client.connect()
design = client.load_design("aes_core", tech="sky130")
print(f"Loaded: {design.cell_count} cells, {design.net_count} nets")

call

def call(
    tool: str,                   # Tool name, e.g. "iPL.place", "iSTA.analyze"
    design: Optional[DesignHandle] = None,
    snap: Optional[SnapshotRef] = None,
    **kwargs,                    # Tool-specific parameters
) -> ToolResult

# Example
result = client.call(
    "iPL.place",
    design=design,
    effort="standard",
    congestion_weight=0.3,
)
print(result.hpwl)     # 1.25e7
print(result.density)  # 0.78

list_tools

def list_tools(
    filter: Optional[str] = None,  # Filter by name prefix, e.g. "iPL.*"
) -> List[ToolDef]

# Example
tools = client.list_tools(filter="iDB.*")
for t in tools:
    print(f"{t.name}: {t.description}")

MCP protocol

Standardized tool invocation via Model Context Protocol. For AI platforms and LLM framework integration.

// List available tools
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

// Response
{
  "tools": [
    {"name": "iDB.snapshot", "description": "...", "inputSchema": {...}},
    {"name": "iPL.place", "description": "...", "inputSchema": {...}}
  ]
}

// Call a tool
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "iPL.place",
    "arguments": {
      "design_ref": "aes_core@sky130",
      "effort": "standard"
    }
  }
}

// Error response
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32602,
    "message": "Invalid params: 'effort' must be one of: quick, standard, exhaustive"
  }
}

Tcl interface

Traditional Tcl CLI for IC engineers. Shares the same iDB instance with Python SDK and MCP.

# Load design
iDB::load_design aes_core sky130

# Take snapshot
iDB::snapshot -label "baseline"

# Place cells
iPL::place -effort standard -congestion_weight 0.3

# Analyze timing
iSTA::analyze -corners {ss_125c tt_25c}

# Get results
puts "WNS: [iSTA::get_wns]"
puts "TNS: [iSTA::get_tns]"
puts "HPWL: [iPL::get_hpwl]"

Common patterns

Error handling

# Python — structured error handling
try:
    result = client.call("iPL.place", design=design, effort="invalid")
except ValidationError as e:
    print(f"Invalid parameter: {e.field} — {e.message}")
except TimeoutError:
    print(f"Tool call timed out after {client.timeout_ms}ms")
except GateFailure as e:
    print(f"Evaluation gate failed: {e.failures}")
except CASConflict as e:
    print(f"CAS conflict — rebase to {e.conflict_with}")

Retry strategy

from ieda import retry

result = retry(
    lambda: client.call("iSTA.analyze", snap=snap.id),
    max_attempts=3,
    backoff_ms=1000,
    on="TimeoutError",
)

Pagination

# Large result sets are paginated
cells = client.call("iDB.query", type="cell", page_size=10000)
while cells.has_next:
    print(f"Processing {len(cells.items)} cells...")
    cells = cells.next_page()

Async invocation

import asyncio

client = AgentClient()
async def parallel_analysis():
    snap = client.call("iDB.snapshot", design=design)
    timing, drc = await asyncio.gather(
        client.async_call("iSTA.analyze", snap=snap.id),
        client.async_call("iDRC.check", snap=snap.id),
    )
    return timing, drc