cyberkat

CyberKat — LLM/agent orchestration on top of CoreKat and TempоKat.

Features

• Canonical I/O envelopes — every agent is f: AgentInput[TContext] → AgentOutput[TResult]. See docs/guides/cyberkat-io.md.
• Langfuse-backed prompt management with local-file fallback, a YAML-driven PromptsRegistry, and a cyberkat prompts CLI for sync / upload / delete operations. See docs/guides/cyberkat-prompts.md.
• Free LLM streaming — BaseWorkflow inherits tempokat.progress.ProgressTracker and routes the on_llm_partial signal into intermediate_results, so every workflow ships token-by-token streaming over the standard SSE endpoint with zero extra plumbing. See docs/guides/cyberkat-progress.md.
• Provider-aware agent configs with model aliasing (AliasResolver), client/api-mode prefix mappings, and DynamicAgentConfig runtime overrides.
• Pluggable extras — install only what you need: cyberkat[llm], cyberkat[docs], cyberkat[langfuse], cyberkat[sentry].
• Configuration management via YAML and environment variables (CoreKat).
• CLI: cyberkat prompts | agents | tikcount | config | version.
• Async-first, Pydantic V2 everywhere, no safeguarded imports.

Installation

From the monorepo root:

# Install this package (core only — no LLM SDKs)
uv sync --package cyberkat

# Or install all packages
uv sync --all-packages

Optional extras:

# LLM/agent support (openai-agents, litellm, openai)
uv pip install "cyberkat[llm]"

# Document export (python-docx, htmldocx, markdown-it-py, fpdf2, openpyxl)
uv pip install "cyberkat[docs]"

# Sentry
uv pip install "cyberkat[sentry]"

# Everything
uv pip install "cyberkat[all]"

Progress tracking & streaming

BaseWorkflow inherits tempokat.progress.ProgressTracker, so every cyberkat workflow exposes the canonical get_progress query and is visible over /api/workflows/progress and /api/workflows/progress/stream out of the box. The on_llm_partial workflow signal routes streamed LLM tokens — emitted by cyberkat.activities.streaming:run_streamed_activity — into tracker.intermediate_results, giving every cyberkat-based service a free token-by-token streaming UI over SSE.

See docs/guides/cyberkat-progress.md for the end-to-end pattern and docs/projectmanagement/epic-cyberkat-v4.md for the full design rationale.

Prompt management

Prompts live outside Python source — managed via Langfuse (optional) with local-file fallback and a YAML registry that maps agents to prompts:

cyberkat prompts list
cyberkat prompts sync --label production
cyberkat agents list --url
cyberkat tikcount --agent ConnyCaseSummaryAgent < draft.md

See docs/guides/cyberkat-prompts.md.

Quick Start

Configuration

Generate a default configuration file:

cyberkat config default-config > config.yaml

Edit config.yaml to customize settings. You can also use environment variables with the CYBERKAT_ prefix.

CLI Usage

# Show version information
cyberkat version

# Generate default config
cyberkat config default-config

# Get help
cyberkat --help

Development

Prerequisites

• Python 3.12+
• uv

Setup

cd cyberkat
uv sync

Testing

# Run tests
make test

# Run tests with coverage
make test-cov

# View coverage report
make coverage

Code Quality

# Run all checks (format, lint, type check, tests)
make check

# Auto-fix formatting and linting issues
make fix

# Format code
make format

# Run linter
make lint

# Run type checker
make pyright

Building

# Build wheel
make build

Project Structure

cyberkat/
├── src/cyberkat/     # Package source code
│   ├── __init__.py             # Package exports and version
│   ├── main.py                 # CLI entry point
│   ├── config.py               # Configuration schema
│   ├── init.py                 # Initialization logic
│   └── cli/                    # CLI commands
├── tests/                      # Test suite
├── make/                       # Build system
│   └── managed.mk              # Managed make targets
├── Makefile                    # Main Makefile
├── pyproject.toml              # Package metadata and dependencies
└── README.md                   # This file

VelociKat Maintenance

This project was generated by VelociKat. To check for updates:

velocikat status
velocikat doctor

License

BSD 3-Clause License. See LICENSE for details.