Metadata-Version: 2.5
Name: katonic-sdk
Version: 7.0.18
Summary: Katonic 7.0 platform SDK — the public API client (KatonicClient), agent authoring, blueprint scaffolding, composition and local evaluation
Project-URL: Homepage, https://www.katonic.ai
Project-URL: Documentation, https://docs.katonic.ai
Author: Katonic.ai
License: Copyright (c) 2026 Katonic.ai. All rights reserved.
        
        Proprietary software. This package is provided under the terms of your
        organization's agreement with Katonic.ai; no rights are granted beyond
        those in that agreement. Redistribution outside its terms is prohibited.
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic>=2.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: ruff==0.15.22; extra == 'dev'
Description-Content-Type: text/markdown

# katonic-sdk

The Python SDK for the Katonic 7.0 platform: the public API client
(`KatonicClient`), agent authoring, blueprint scaffolding, multi-agent
composition, and local evaluation.

```bash
pip install "katonic-sdk>=7"
# or pin it to the version of the platform you deploy (X.Y.Z):
pip install "katonic-sdk==X.Y.Z"
```

Sovereign / air-gapped installs: download the wheel from your deployment's
Developer Hub instead.

## Quickstart

```bash
export KATONIC_BASE_URL=https://<your-studio-host>   # the host; the client adds /public/v1
export KATONIC_API_KEY=kapi_...                      # Studio > Public API > API keys
```

```python
import asyncio
from katonic import KatonicClient

async def main():
    async with KatonicClient() as k:  # reads KATONIC_API_KEY / KATONIC_BASE_URL
        agent = (await k.list_agents())[0]  # published agents; chat takes the agent's id
        resp = await k.chat(agent.id, "What is the PTO policy?")
        print(resp.message.content)

asyncio.run(main())
```

The `katonic` command ships with the package (`katonic login`,
`katonic agents list`, `katonic search …` — see `katonic --help`).

## What the client covers

`KatonicClient` wraps the platform's public API, one async method per call:

| Area | Methods |
|---|---|
| Agents | `list_agents`, `get_agent`, `create_agent`, `update_agent`, `publish_agent` |
| Chat and sessions | `chat`, `chat_stream`, `create_session`, `list_sessions`, `get_history`, `delete_session`, `submit_feedback` |
| Models | `list_models`, `get_model`, `completions` (OpenAI-compatible) |
| Knowledge | `list_sources`, `create_source`, `upload_documents`, `ingest`, `sync_source`, `search` |
| Knowledge graph | `load_graph`, `get_graph_schema`, `query_graph` |
| Graph schemas | `list_ontologies`, `create_ontology`, `get_ontology`, `update_ontology`, `publish_ontology`, `new_ontology_version`, `delete_ontology`, `validate_ontology`, `discover_ontology`, `list_source_ontologies`, `attach_ontology`, `detach_ontology`, `set_ontology_mode`, `baseline_ontology_violations` |
| Evaluation | `list_datasets`, `upload_dataset`, `run_evaluation`, `get_evaluation`, `poll_evaluation`, `compare_evaluations` |
| Prompt optimization | `optimize_prompt`, `get_optimization`, `poll_optimization` |
| Data flywheel | `ingest_traces`, `get_quality_trend`, `build_flywheel_dataset` |
| Skills | `list_skills`, `get_skill`, `import_skills` |
| Tools | `list_tools`, `execute_tool` |
| Guardrails | `evaluate_guardrails` |
| Usage and cost | `get_usage`, `get_analytics_usage`, `get_cost_breakdown` |

Each call needs the matching scope on the key. A few are refused by the
platform whatever the key holds, while the public API does not yet allow them:
creating knowledge sources, uploading documents, and creating, changing,
validating or deleting graph schemas.

The rest of the package authors agents offline, with no platform:

- `katonic.gateway`, `katonic.knowledge`, `katonic.guardrails` and
  `katonic.tools` build an agent's bindings;
- `katonic.compose` wires sub-agents into NAT workflows;
- `katonic.scaffold` writes blueprint packages;
- `katonic.evaluate` writes local evaluation configs;
- `katonic.connectors` is the base class for custom knowledge connectors.

## Naming, versioning, and one caveat

- **Distribution name**: `katonic-sdk`, from 7.x (this package). The 6.x
  releases under the same name are Katonic's *legacy MLOps* SDK, a different
  API: pin `katonic-sdk<7` if you still need it. Earlier 7.x documentation
  called this package `katonic-platform`; it was never published under that
  name.
- **Import name**: `import katonic`. The legacy `katonic` 6.2.0 package owns
  the same import name — installing both in one environment is a silent
  module collision. Keep them in separate environments.
- **Versioning**: the SDK is released with the platform, at the platform's
  version: platform `vX.Y.Z` is `katonic-sdk==X.Y.Z`. Development builds,
  `X.Y.Z.devN`, are published to TestPyPI only. Install the version that
  matches your deployment. A newer SDK can call routes that an older platform
  does not have.

## Support

Issues and questions go through your Katonic support channel; the API
reference lives in your deployment's Developer Hub.
