Metadata-Version: 2.4
Name: kyber-cli
Version: 4.0.1
Summary: Kyber Developer Experience CLI — deploy agents in one command
Author-email: Symplii <hello@symplii.ai>
License: Apache-2.0
Keywords: kyber,agent,cli,deployment
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: kyber-sdk>=1.1.0
Requires-Dist: click>=8.1.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: PyJWT[crypto]>=2.8.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyfiglet>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: jsonschema>=4.17.0
Requires-Dist: pywin32>=305; sys_platform == "win32"
Requires-Dist: pytest-cov>=4.0.0
Requires-Dist: pytest>=7.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"

# Kyber CLI

Kyber CLI is a developer-experience command line for scaffolding, validating, running, and preparing AI agents for deployment. It gives you a small local project, managed runtime guardrails, structure validation, deterministic version pinning, and deploy-preview generation from one command surface.

Version: `2.0.0`

## Features

- Scaffold Python agent projects with generated config, circuit, manifest, tests, and runtime guardrails.
- Validate config schema, required project structure, managed runtime files, and Kyber CLI compatibility before execution.
- Run handlers or circuits locally through the Kyber-managed runtime wrapper.
- Preview expanded deploy manifests with platform defaults.
- Eject defaults for explicit customization.
- Pin the Kyber CLI version per repo or per machine.
- Print deterministic installer commands for exact CLI versions.

## Installation

### Development Install

```powershell
git clone https://github.com/kyber/cli.git
cd cli
pip install -e .
```

### Verify

```powershell
kyber --version
kyber --help
```

## Quick Start

```powershell
kyber login
kyber design init invoice-parser --runtime python
cd invoice-parser
kyber design validate
kyber exec run circuit
kyber exec deploy --dry-run
```

For an end-to-end runtime walkthrough covering Memory, tools, LLM telemetry,
automatic pricing, local testing, and deployment, see
[Using Memory, Tools, and Telemetry with Kyber CLI](docs/RUNTIME_SERVICES_GUIDE.md).

Generated project layout:

```text
invoice-parser/
|-- kyber.agent.json
|-- kyber.circuit.json
|-- manifest.json
|-- requirements.txt
|-- pytest.ini
|-- .kyber/
|   |-- runtime.lock.json
|   |-- runtime_wrapper.py
|   `-- direct_run_guard.py
|-- src/
|   `-- handler.py
`-- tests/
    |-- conftest.py
    |-- test_handler.py
    |-- test_circuit.py
    |-- test_guardrails.py
    `-- fixtures/
        `-- sample_event.json
```

## Command Reference

### Primary Commands

| Command | Purpose | Example |
| --- | --- | --- |
| `kyber design init` | Scaffold an agent project | `kyber design init my-agent --runtime python` |
| `kyber design validate` | Validate config, structure, runtime guardrails, and CLI compatibility | `kyber design validate` |
| `kyber design test` | Run the agent project's pytest test suite | `kyber design test -v` |
| `kyber design explain` | Show platform defaults and customization hints | `kyber design explain --capability workflow` |
| `kyber design explain defaults` | Inspect versioned defaults profile values | `kyber design explain defaults --profile standard --key identity.client_id` |
| `kyber design eject` | Export manifest section defaults for customization | `kyber design eject workflow` |
| `kyber exec run` | Run a handler or circuit through the managed runtime | `kyber exec run circuit` |
| `kyber exec deploy` | Preview or prepare deployment output | `kyber exec deploy --dry-run` |
| `kyber tools` | List active tools from the Tool Gateway registry | `kyber tools` |
| `kyber tools --tool` | Show one registered tool's invocation contract | `kyber tools --tool weather-api` |
| `kyber exec status` | Show local runtime/audit status | `kyber exec status` |
| `kyber pin` | Pin the Kyber CLI version per repo or machine | `kyber pin --scope repo --version 2.0.0` |
| `kyber self-update` | Print an exact installer command for a CLI version | `kyber self-update --version 2.0.0 --manager pip` |
| `kyber compat` | Show compatibility and pin precedence rules | `kyber compat` |
| `kyber login` | Authenticate to the platform | `kyber login` |

Legacy aliases such as `kyber init`, `kyber validate`, `kyber run`, `kyber status`, `kyber test`, `kyber deploy`, `kyber explain`, and `kyber eject` remain callable for compatibility, but lifecycle groups are the preferred command surface.

### Tool Gateway registry

Browse the tools currently available through the Kyber Tool Gateway:

```bash
kyber tools
kyber tools --tool weather-api
```

Both commands also accept `--json` for machine-readable output. The Tool Gateway
URL and platform shared secret are packaged in
`kyber/tool_gateway/config.json`. When needed, the URL can be overridden without
moving the secret into developer configuration:

```bash
KYBER_TOOL_GATEWAY_BASE_URL=http://127.0.0.1:8011
```

The non-sensitive URL can also be stored under `tool_gateway.base_url` in the
Kyber machine `config.json`. The shared secret is always loaded from the packaged
Tool Gateway configuration, never from the developer's machine config or
environment variables.

Tool registry responses are cached for 30 minutes in the CLI-managed machine
cache at `cache/tool-registry.json` under the Kyber config directory (for example,
`%LOCALAPPDATA%\kyber\cache\tool-registry.json` on Windows). `kyber tools`, tool
detail lookup, and `kyber design validate` share this cache. A missing, invalid, or
expired cache is refreshed from the Tool Gateway API. Authentication secrets are
never written to the cache.

Declared tools require explicit least-privilege permissions. `kyber validate`
checks each permission against the tool's cached `supported_operations`. For
example, if `manual-vendor-pricing-api` supports `query`:

```json
{
  "tools": ["manual-vendor-pricing-api"],
  "integrations": {
    "data_access": [
      {
        "source": "manual-vendor-pricing-api",
        "permissions": ["query"]
      }
    ],
    "external_apis": ["manual-vendor-pricing-api"]
  }
}
```

### Tool invocation from agent code

For the complete developer workflow, including local credentials, response
decoding, troubleshooting, and governed deployment behavior, see
[Calling Kyber Tools from an Agent](docs/TOOL_INTEGRATION_GUIDE.md).

Python agents use one API for local and deployed tool calls:

```python
from kyber.tools import invoke_tool

tool_call = invoke_tool(
    "manual-vendor-pricing-api",
    "query",
    {"sku": "ABC-123"},
)
```

For a local integration run, use the normal run command:

```powershell
kyber exec run agent --event-file event.json
```

When the agent manifest declares tools, `kyber exec run` automatically invokes
`POST /api/v1/local/tools/invoke`. This local-only endpoint uses
the registered adapter but skips Identity, Vault, platform idempotency, telemetry,
cost metering, and incident signals.

Tools requiring credentials can use a developer-owned, gitignored
`.kyber/local-tool-credentials.json` file:

```json
{
  "tools": {
    "example-tool": {
      "bindings": {
        "default": {
          "api_key": {"value": "developer-owned-key"}
        }
      }
    }
  }
}
```

Use `--local-tool-credentials <path>` to select another file. Credentials are
sent only to the local endpoint and are not written to platform services.
The former `--local-tools` flag remains accepted for command compatibility but
no longer controls transport selection.

In a deployment, the Kyber platform supplies internal routing and authentication.
The same agent API submits the invocation to the platform runtime. Its current
response has `status="accepted"`; completed tool output will become available
after the platform result-delivery contract is implemented.

### Memory access from agent code

The CLI package exposes an asynchronous gRPC client for direct Memory Service
reads and orchestrator-mediated writes:

```python
from kyber.memory import get_memory


async def run(context):
    async with get_memory(context) as memory:
        preferences = await memory.get(
            "preferences",
            scope="user",
            user_id="user-123",
            project_id="project-456",
        )

        await memory.write(
            "preferences",
            {"tone": "concise"},
            scope="user",
            user_id="user-123",
            project_id="project-456",
            memory_type="structured",
            idempotency_key=context.request_id,
        )
```

Developers provide the identifiers required by the requested scope. User scope
requires `user_id` and `project_id`; project scope requires `project_id`; session
scope requires `user_id`, `project_id`, and `session_id`. Tenant, agent, circuit,
endpoint, and authentication values are supplied by the runtime context or these
environment variables:

```text
KYBER_TENANT_ID
KYBER_EXECUTION_ID
KYBER_AGENT_ID
KYBER_CIRCUIT_ID
KYBER_MEMORY_GRPC_TARGET
KYBER_MEMORY_WRITE_GRPC_TARGET
KYBER_MEMORY_PLATFORM_AUTH
KYBER_MEMORY_GRPC_TLS
KYBER_MEMORY_GRPC_ROOT_CERTIFICATE
KYBER_MEMORY_GRPC_TIMEOUT_SECONDS
```

`KYBER_MEMORY_GRPC_TARGET` is the direct-read Memory Service target.
`KYBER_MEMORY_WRITE_GRPC_TARGET` identifies E3 Runtime's mediated write endpoint;
it deliberately does not fall back to the direct-read target. E3 uses
`KYBER_EXECUTION_ID` to correlate the write with E5. TLS is enabled by default.

For a local agent run, the CLI owns the local configuration and service lifecycle:

```powershell
kyber exec run agent --event '{"schema_version":"v1","artifact_type":"agent-input-v1","data":{"user_id":"user-123","project_id":"project-456"}}'
```

The developer supplies `user_id` and `project_id` to the memory operation. The CLI
derives tenant, agent, and circuit identity from the project, starts local read and
write gRPC endpoints, injects their test credentials, and stops them after the run.
Memory records persist in `.kyber/local-memory.db`, so later local runs in the same
project can access them. No Memory environment variables or external services are
required.

The former `--local-memory` flag remains accepted for command compatibility but
is no longer required. All `kyber exec run` executions use the project-local
Memory backend. Deployed agents do not execute through this command; their runtime
context supplies the platform Memory Service targets and credentials instead.

To keep the database-free service alive across several manual runs, start it in a
separate terminal:

```powershell
kyber memory serve
```

It stores data in `.kyber/local-memory.db` by default and exposes separate read and
write endpoints to preserve the production call shape without requiring E5, E10,
E12, PostgreSQL, or Redis. Use `--storage-file` to select another local SQLite file.
Configure the agent terminal with the printed test-only values:

```powershell
$env:KYBER_MEMORY_GRPC_TARGET = "127.0.0.1:50110"
$env:KYBER_MEMORY_WRITE_GRPC_TARGET = "127.0.0.1:50111"
$env:KYBER_MEMORY_PLATFORM_AUTH = "local-platform-secret"
$env:KYBER_MEMORY_GRPC_TLS = "false"
```

The local service is a contract-compatible development backend, not E5 or E10.
Its contents remain in the configured SQLite file until that file is removed.

## Design Commands

### `kyber design init`

Create a new agent project.

```powershell
kyber design init my-agent
kyber design init support-bot --runtime python
kyber design init calendar-agent --runtime python --tools calendar --tools email
```

Options:

- `--runtime`: Agent runtime. Supported: `python`, `node`, `go`.
- `--tools`: Tool name to enable. Repeat the flag for multiple tools.
  `--tool-id` remains available as an alias.

### `kyber design validate`

Validate the current project without a network call.

```powershell
kyber design validate
kyber design validate --path ./agents/my-agent/kyber.agent.json
kyber design validate --verbose
```

Validation checks:

- `kyber.agent.json` syntax and schema version.
- Required config fields: `schema_version`, `name`, `runtime`, `tools`, and `entrypoint`.
  `version` defaults to `1.0.0` when omitted.
- Required generated files and directories are present and correctly placed.
- Python entrypoint lives under `src/`.
- Managed runtime wrapper, direct-run guard, and runtime lock are present and hash-valid.
- Runtime lock was generated by a compatible Kyber CLI major version.
- Active repo or machine pin matches the installed Kyber CLI exactly.

Example failure:

```text
Validation failed
  - Required file missing or moved: requirements.txt. Restore the file at requirements.txt or rerun 'kyber design init <name>' and copy your changes into the generated layout.
  - Kyber DX 2.0.0 does not match the active repo pin 2.0.1 at .kyber/dx.json. Install the pinned version with 'kyber self-update --version 2.0.1' or update the pin with 'kyber pin --scope repo --version 2.0.0'.
```

### `kyber design test`

Run the agent project's pytest test suite from the current agent project.

```powershell
kyber design test
kyber design test -v
kyber design test -k handler
kyber design test --stop-on-first-failure
```

Options:

- `--path`, `-p`: Path to the test directory or a specific test file. Default: `tests`
- `--verbose`, `-v`: Verbose pytest output.
- `--coverage`, `-c`: Generate coverage report (requires `pytest-cov`).
- `--markers`, `-m`: Run pytest markers using `-m`.
- `--keyword`, `-k`: Run pytest keyword expressions using `-k`.
- `--stop-on-first-failure`, `-x`: Stop execution when the first test fails.
- `--show-locals`, `-l`: Show local variables in tracebacks.

### `kyber design explain`

Inspect platform defaults and how to override them.

```powershell
kyber design explain --capability workflow
kyber design explain defaults
kyber design explain defaults --profile standard
kyber design explain defaults --profile regulated --key cost_and_telemetry.telemetry_intent
kyber design explain defaults --profile high-volume --json
```

Use `kyber design explain` without a topic from inside an agent project to see the defaults that are applied to that agent after tier/profile detection. Use the `defaults` topic to inspect the versioned defaults registry directly, even when you only want one dotted key.

Options for `kyber design explain defaults`:

- `--profile`: Defaults profile to inspect. Supported profiles are `minimal`, `standard`, `regulated`, and `high-volume`. Default: `standard`.
- `--version`: Defaults profile version to inspect. When omitted, Kyber uses the current version for the selected profile.
- `--key`: Dotted defaults path to show, such as `identity.client_id`, `workflow.execution_mode`, or `memory_capabilities.scope_access`.
- `--json`: Print machine-readable JSON output.

### Team Custom Profiles

Teams can share custom defaults profiles by committing `kyber.profiles.json` at the agent project root. Custom profile names use lowercase letters, numbers, and hyphens, and can extend a built-in profile while overriding only selected dotted defaults.

```json
{
  "profiles": {
    "team-secure": {
      "extends": "regulated",
      "metadata": {
        "name": "Team Secure",
        "description": "Team security baseline",
        "tier": 2
      },
      "versions": {
        "1.0": {
          "defaults": {
            "deployment_metadata.profile": "team-secure",
            "cost_and_telemetry.max_cost_usd": 25,
            "cost_and_telemetry.telemetry_intent": ["logs", "events"]
          }
        }
      }
    }
  }
}
```

Then select it from `kyber.agent.json`:

```json
{
  "profile": "team-secure"
}
```

### Defaults Commands

Kyber has a versioned defaults registry for platform-managed manifest sections. The public agent workflow normally uses:

```powershell
kyber design explain defaults
kyber explain defaults
kyber design explain defaults --profile standard --key identity.client_id
kyber exec deploy --dry-run
```

`kyber design explain defaults` is the preferred lifecycle command. `kyber explain defaults` remains available as a compatibility alias.

Some builds or internal/platform tooling may also expose the lower-level `kyber defaults` command group. It contains:

```powershell
kyber defaults explain --profile standard
kyber defaults explain --profile standard --version 1.0
kyber defaults explain --profile regulated --key cost_and_telemetry.telemetry_intent
kyber defaults explain --profile high-volume --json

kyber defaults migrate --profile standard --from 1.0 --to 1.0
kyber defaults migrate --agent agent-1@default:1.0.0
kyber defaults migrate --agent agent-1@default:1.0.0 --accept-breaking
kyber defaults migrate --profile regulated --from 1.0 --to 1.0 --json

kyber defaults pin --agent agent-1@default:1.0.0 --profile standard
kyber defaults pin --agent agent-1@default:1.0.0 --profile standard --version 1.0
kyber defaults pin --agent agent-1@default:1.0.0 --profile standard --json
```

Command behavior:

- `kyber defaults explain`: Shows defaults metadata and values for a profile/version. Use `--key` to inspect one dotted path, or `--json` for machine-readable output.
- `kyber defaults migrate`: Shows changes between defaults versions. Use `--agent` to read that agent's existing defaults pin, or provide `--profile` and `--from` manually. Breaking changes require `--accept-breaking` before an agent pin is updated.
- `kyber defaults pin`: Writes or updates the local defaults pin for an agent. Deploy also writes a defaults pin automatically after preparing a local MVP deployment handoff.

Options:

- `kyber defaults explain`: `--profile`, `--version`, `--key`, `--json`.
- `kyber defaults migrate`: `--profile`, `--from`, `--to`, `--agent`, `--accept-breaking`, `--json`.
- `kyber defaults pin`: `--agent`, `--profile`, `--version`, `--json`.

Defaults pins are stored under `.kyber/deployments/` and record the agent id, defaults profile, defaults version, platform release, and update timestamp. They are local audit metadata; they do not call real services.

**Total time: < 5 minutes** ⚡

---

## 📚 Command Reference

### Core Commands

| Command | Purpose | Example |
|---------|---------|---------|
| `kyber init` | Create new agent project | `kyber init my-agent --runtime python` |
| `kyber validate` | Check config syntax & schema | `kyber validate` |
| `kyber test` | Run the project's pytest suite | `kyber test -v` |
| `kyber deploy` | Deploy to environment | `kyber deploy --env prod` |
| `kyber run` | Run a handler or circuit locally | `kyber run circuit` |
| `kyber status` | Show local runtime/audit status | `kyber status` |
| `kyber explain` | Show applied defaults | `kyber explain --capability workflow` |
| `kyber eject` | Export manifest section config for customization | `kyber eject workflow` |
| `kyber pin` | Pin CLI version per repo or machine | `kyber pin --scope repo --version 2.0.0` |
| `kyber self-update` | Print deterministic installer command | `kyber self-update --version 2.0.0 --manager pip` |
| `kyber compat` | Show CLI/runtime compatibility metadata | `kyber compat --json` |
| `kyber login` | Authenticate to platform | `kyber login` |

### Detailed Usage

#### `kyber compat` - Show CLI Compatibility Metadata

Expose the installed Kyber CLI version and the supported runtime lock version range.

```powershell
kyber compat

# Machine-readable
kyber compat --json
```

`kyber compat --json` exposes:

```json
{
  "dx_version": "2.0.0",
  "supported_runtime_version_range": "2.x.x"
}
```

Runtime locks generated by the same Kyber CLI major version are compatible. Execution is blocked when the active repo/machine pin does not match the installed CLI.

---

#### `kyber init` — Scaffold New Agent

Create a minimal agent project with a compact configuration.

```powershell
kyber design eject workflow
kyber design eject identity
kyber design eject intelligence
kyber design eject memory_capabilities --intent write
kyber design eject memory_capabilities --injection enable
kyber design eject all
```

Typical customization flow:

```powershell
kyber design eject workflow
notepad workflow.json
kyber exec deploy --dry-run
```

## Execution Commands

### `kyber exec run`

Run a handler or circuit through the Kyber-managed runtime. Execution is blocked if validation, structure, runtime guardrail, or CLI compatibility checks fail.

```powershell
kyber exec run
kyber exec run circuit
kyber exec run --event '{"input": "hello"}'
kyber exec run --event-file tests/fixtures/sample_event.json
kyber exec run circuit --circuit-file kyber.circuit.json
```

Options:

- `--event`, `-e`: Inline JSON event payload.
- `--event-file`, `-f`: Path to a JSON event file.
- `--circuit-file`: Circuit JSON file used when running `circuit`.

### `kyber exec deploy`

Expand config with platform defaults and preview or prepare deployment output.

```powershell
kyber exec deploy --dry-run
kyber exec deploy --env dev
kyber exec deploy --env stage
kyber exec deploy --env prod
```

Options:

- `--env`: Target environment. Supported: `dev`, `stage`, `prod`. Default: `dev`.
- `--dry-run`: Print expanded config and generated manifest without deploying.
- `--manifest-path`: Output path for the generated manifest. Default: `manifest.json`.

### `kyber exec status`

Show local runtime/audit state.

```powershell
kyber exec status
kyber exec status --path .
kyber exec status --limit 20
```

## Versioning Commands

Kyber supports deterministic CLI versioning. Pins are explicit, installer commands use exact versions, and execution is blocked when the active pin or runtime lock is incompatible.

### `kyber pin`

Pin the Kyber CLI version for the current repo or the current machine.

```powershell
kyber pin --scope repo --version 2.0.0
kyber pin --scope machine --version 2.0.0
```

Pin files:

- Repo pin: `.kyber/dx.json`
- Machine pin on Windows: `C:\Users\<you>\AppData\Local\kyber\dx.json`
- Machine pin on Linux/macOS: `~/.kyber/dx.json`

Precedence:

1. Repo pin wins when `.kyber/dx.json` exists.
2. Machine pin is used when no repo pin exists.
3. No pin means the installed CLI is accepted, subject to runtime lock compatibility.

### `kyber self-update`

Print a deterministic installer command for an exact Kyber CLI version. This command intentionally avoids floating `latest` installs.

```powershell
kyber self-update --version 2.0.0 --manager pip
kyber self-update --version 2.0.0 --manager pipx
kyber self-update
```

If `--version` is omitted, Kyber uses the active pin when present, otherwise the currently installed CLI version.

### `kyber compat`

Show compatibility and pin precedence rules.

```powershell
kyber compat
```

Policy summary:

- Runtime locks generated by the same Kyber CLI major version are compatible.
- Future or different-major runtime locks block execution.
- Repo pins override machine pins.
- Active pins must exactly match the installed Kyber CLI version.

## Authentication

```powershell
kyber login
kyber login --env stage
kyber login --no-browser
```

Options:

- `--env`: Target environment. Supported: `dev`, `stage`, `prod`. Default: `prod`.
- `--no-browser`: Print auth URL instead of opening a browser.
- `--issuer`, `--client-id`: Override the Keycloak OIDC settings for one login.

The package contains its per-environment public Keycloak OIDC metadata, including
the loopback redirect URI, in `kyber/auth/config.json`. Register `kyber-cli` as a
public Keycloak client using Authorization Code + PKCE (S256), enable the
`organization` and `offline_access` scopes, allow the loopback redirect
`http://127.0.0.1:8765/callback`, and place the public client ID in that catalog.
Users can then sign in without setting authentication environment variables:

```powershell
kyber login --env dev
```

The command options and `KYBER_OIDC_*` variables remain optional overrides for
local identity-provider testing; they are not normal end-user configuration.
After OIDC succeeds, the CLI calls `/v1/auth/context` once and stores that response
in the machine login configuration. The authenticated tenant UUID is cached as
`user.tenant_id`; later deployment steps reuse the cached context rather than
calling the endpoint again. The external Keycloak organization value remains
available as `user.organization_id`.

The CLI requests the Keycloak organization claim and requires exactly one active
organization. Access tokens are refreshed automatically when Keycloak returns an
`offline_access` refresh token.

Token storage on Windows: `C:\Users\<you>\AppData\Local\kyber\config.json`

## Configuration

Minimum authored config lives in `kyber.agent.json`:

```json
{
  "schema_version": "v1",
  "name": "invoice-parser",
  "version": "1.0.0",
  "runtime": "python",
  "tools": [],
  "entrypoint": "src/handler.py"
}
```

The config schema version (`schema_version`) describes the shape of `kyber.agent.json`; keep it explicit so future schema versions can be selected intentionally. New projects set the agent version (`version`) to `1.0.0`; update it with your own semantic version as the agent evolves. The defaults engine maps this value to `identity.version` in the generated manifest. Developer-provided config wins over defaults.

Optional authored sections are `capability`, `interaction`, `configuration`, `integrations`, `cost_and_telemetry`, `memory_capabilities`, `memory`, `governance`, `orchestration`, `identity`, `gateway`, `governed_objects`, `lifecycle`, `commercial`, `intelligence`, and `policy_engine`. Authored config is validated by Kyber's config model; generated deploy manifest JSON Schemas are published as `kyber/core/schemas/kyber.manifest.vN.schema.json`.

Declare direct user input separately from agent-to-agent artifact inputs. The input is passed unchanged to the handler as `event["user_input"]`; the empty `properties` map and `additionalProperties: true` allow any number of user-defined fields:

```json
"interaction": {
  "user_input": {
    "mode": "required",
    "schema": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  }
}
```

The config `schema_version` selects the manifest schema major version generically: `vN` uses manifest schema `N.0.0` and `kyber/core/schemas/kyber.manifest.vN.schema.json`. To add `v3`, `v4`, `v5`, or later, add the matching schema file. To make that schema the default for newly initialized projects, update `AGENT_CONFIG_SCHEMA_VERSION` in `kyber/core/schema_version.py`.

Use `kyber design eject <section>` to customize defaulted sections without adding them to `kyber.agent.json`. For example, `kyber design eject workflow` creates `workflow.json`; edits to that file are merged into the generated `manifest.json` on deploy.

### Built-in LLM instrumentation

Python agents run through Kyber's managed local and deployment execution paths, which install the instrumentation before invoking user code. Developers use the normal OpenAI, Anthropic, or LangChain clients; no separate telemetry package or LLM wrapper call is required. Declare every provider/model in `capability.llm_models`:

```json
{
  "capability": {
    "llm_models": [
      {"provider": "openai", "name": "gpt-5", "version": "2026-08"}
    ]
  }
}
```

E3 invokes a deployed agent with a trusted envelope and receives the handler result plus the aggregated usage summary:

```json
{
  "context": {
    "instruction_id": "11111111-1111-4111-8111-111111111111",
    "execution_id": "22222222-2222-4222-8222-222222222222",
    "circuit_id": "33333333-3333-4333-8333-333333333333",
    "trace_id": "trace-123",
    "tenant_id": "44444444-4444-4444-8444-444444444444",
    "agent_id": "agent-123",
    "agent_version": "1.0.0"
  },
  "input": {"prompt": "hello"}
}
```

Each supported LLM call emits an `agent.llm.call_recorded` usage and cost signal to E8. E3 is responsible for publishing agent-run telemetry to E7; the agent runtime does not publish directly to E7. Configure the deployed pod with:

- `KYBER_TELEMETRY_EXPORTER=http`
- `KYBER_E8_SIGNAL_URL=https://...`
- `KYBER_PLATFORM_AUTH=...` (optional platform header)

Kyber ships with a versioned pricing snapshot and refreshes its local cache from the
LiteLLM community catalog at most once every 24 hours. No project pricing file is
required. If `OPENROUTER_API_KEY` is configured, Kyber also refreshes prices from
OpenRouter's Models API and applies those prices only to calls whose provider is
`openrouter`. Network failures fall back to the last valid cache and then to the
bundled snapshot.

`KYBER_LLM_PRICING_FILE=/path/to/pricing.json` remains available as an explicit
override. `KYBER_LLM_PRICING_REFRESH=0` disables network refresh, and
`KYBER_LLM_PRICING_CACHE` changes the cache location. Unknown pricing or missing
provider usage is reported as `cost_completeness: partial`; it is never silently
treated as complete zero cost. For local development, the default exporter prints
each structured JSON event to the console; use `KYBER_TELEMETRY_EXPORTER=file` and
`KYBER_TELEMETRY_FILE=.kyber/telemetry.jsonl` for JSONL file output, or `none` to
disable export.

`kyber design validate` rejects undeclared supported LLM providers and direct Python HTTP/socket clients under `src/`. External capabilities must be declared as tools and invoked through the Kyber Tool Gateway.

## Typical Workflow

```powershell
kyber design init invoice-parser --runtime python
cd invoice-parser

notepad src/handler.py

kyber design validate
kyber exec run circuit
kyber design explain --capability workflow
kyber exec deploy --dry-run

kyber design eject workflow
notepad workflow.json
kyber exec deploy --dry-run
```

## Development

Run tests:

```powershell
.\venv\Scripts\python.exe -m pytest
```

Validation checklist:

```powershell
kyber --version
kyber --help

kyber design init test-agent --runtime python
cd test-agent

kyber design validate
kyber exec run circuit
kyber design explain --capability workflow
kyber design eject workflow
kyber exec deploy --dry-run

kyber pin --scope repo --version 2.0.0
kyber compat
kyber self-update --version 2.0.0 --manager pip
```

## Current Limitations

| Feature | Status |
| --- | --- |
| Real deployments | `--dry-run` and manifest generation are available; control-plane integration is pending. |
| OIDC authentication | Stub implementation for local development. |
| Container registry push | Not implemented yet. |
| Usage telemetry | Built in for supported Python OpenAI, Anthropic, and LangChain calls; other runtimes/providers require an adapter. |

## Support

- Documentation: https://kyber.ai/docs
- Issues: https://github.com/kyber/cli/issues
- Email: support@kyber.ai

## Roadmap

- Control Plane API integration for real deployments.
- Production OIDC authentication flow.
- Container registry integration.
- Interactive config builder.
- Real-time deployment logs.

## License

This project is licensed under the MIT License.

