Architecture

Architecture

Zinc runs Circuitry graphs against local runtime effects.

Circuitry owns graph semantics. Zinc owns effects: model endpoint calls, tools, packages, sessions, runtime URIs, config, permissions, and local project layout.

Responsibility split

Layer	Owns
Circuitry	YAML graph source, imports, exports, addresses, schemas, dependency planning, resource reachability
Zinc	model calls, tool execution, package installation, sessions, URI materialization, config, project layout, permissions

This split keeps graph files portable. A graph says what should happen. Zinc decides how runtime effects are performed on this machine.

Endpoint-only model

Zinc speaks OpenAI-compatible Chat Completions.

Zinc does not:

• bundle a model
• pick a default hosted provider
• download model files
• build inference engines
• start local inference servers

A model is a configured endpoint:

default_model: local

models:
  local:
    model: model-name-served-by-your-endpoint
    base_url: http://127.0.0.1:30000/v1
    api_key_env:
    context_window: 8192
    chars_per_token: 4

The graph says where a model call belongs. Runtime config says which endpoint serves it.

Run flow

1. Zinc loads runtime config and the selected graph.
2. Circuitry validates graph shape and resolves the selected export.
3. Zinc materializes reachable resources.
4. A model resource builds model messages from declared inputs.
5. The model may call declared tools.
6. Zinc validates tool arguments and runs the builtin or package handler.
7. Tool results return to the model loop.
8. Zinc appends session messages and returns the final text or validated JSON.

Explicit model visibility

A Zinc model resource is a boundary. It only receives inputs declared in the graph:

resources:
  assistant:
    model:
      identity: Zinc
      input:
        - $user_turn
        - bash_guide
      tools:
        - read
        - bash
      instructions: Answer directly.

Nothing else is implicitly included. Package install patches are visible in graph source and reviewable in diffs.

Effects boundary

Zinc runtime effects are intentionally narrow:

• read, write, and edit files through approved tools
• execute shell through policy-controlled bash
• run graph exports through run_graph
• call configured model endpoints
• call package tools through declared external handlers
• persist and compact sessions

Anything outside that boundary belongs in a package, a graph, or the user’s own local setup.