Metadata-Version: 2.4
Name: cyberkat
Version: 0.1.0
Summary: cyberkat library
Author-email: velocikat <velocikat@lza.sh>
Requires-Python: >=3.12
Requires-Dist: corekat>=0.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tempokat>=0.1.0
Requires-Dist: tiktoken>=0.7
Provides-Extra: all
Requires-Dist: fpdf2; extra == 'all'
Requires-Dist: htmldocx; extra == 'all'
Requires-Dist: langfuse>=2.0; extra == 'all'
Requires-Dist: litellm; extra == 'all'
Requires-Dist: markdown-it-py; extra == 'all'
Requires-Dist: openai; extra == 'all'
Requires-Dist: openai-agents>=0.1.0; extra == 'all'
Requires-Dist: openpyxl; extra == 'all'
Requires-Dist: python-docx; extra == 'all'
Requires-Dist: sentry-sdk; extra == 'all'
Provides-Extra: docs
Requires-Dist: fpdf2; extra == 'docs'
Requires-Dist: htmldocx; extra == 'docs'
Requires-Dist: markdown-it-py; extra == 'docs'
Requires-Dist: openpyxl; extra == 'docs'
Requires-Dist: python-docx; extra == 'docs'
Provides-Extra: langfuse
Requires-Dist: langfuse>=2.0; extra == 'langfuse'
Provides-Extra: llm
Requires-Dist: litellm; extra == 'llm'
Requires-Dist: openai; extra == 'llm'
Requires-Dist: openai-agents>=0.1.0; extra == 'llm'
Provides-Extra: sentry
Requires-Dist: sentry-sdk; extra == 'sentry'
Description-Content-Type: text/markdown

# 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`](../../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`](../../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`](../../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:

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

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

Optional extras:

```bash
# 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`](../../docs/guides/cyberkat-progress.md)
for the end-to-end pattern and
[`docs/projectmanagement/epic-cyberkat-v4.md`](../../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:

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

See [`docs/guides/cyberkat-prompts.md`](../../docs/guides/cyberkat-prompts.md).

## Quick Start

### Configuration

Generate a default configuration file:

```bash
cyberkat config default-config > config.yaml
```

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

### CLI Usage

```bash
# Show version information
cyberkat version

# Generate default config
cyberkat config default-config

# Get help
cyberkat --help
```

## Development

### Prerequisites

-   Python 3.12+
-   [uv](https://astral.sh/uv)

### Setup

```bash
cd cyberkat
uv sync
```

### Testing

```bash
# Run tests
make test

# Run tests with coverage
make test-cov

# View coverage report
make coverage
```

### Code Quality

```bash
# 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

```bash
# 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:

```bash
velocikat status
velocikat doctor
```

## License

BSD 3-Clause License. See [LICENSE](../../LICENSE) for details.
