Metadata-Version: 2.4
Name: kronos-agent-os
Version: 0.3.0
Summary: Kronos Agent OS (KAOS): self-hosted runtime for durable AI agents with memory, skills, MCP tools, automations, and sub-agent coordination
License-Expression: MIT
Project-URL: Homepage, https://github.com/spyrae/kronos-agent-os
Project-URL: Repository, https://github.com/spyrae/kronos-agent-os
Project-URL: Issues, https://github.com/spyrae/kronos-agent-os/issues
Project-URL: Documentation, https://github.com/spyrae/kronos-agent-os/tree/main/docs
Keywords: ai-agents,agent-os,mcp,memory,skills,self-hosted,swarm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core>=0.3
Requires-Dist: openai>=1.0
Requires-Dist: langchain-openai>=0.3
Requires-Dist: langchain-deepseek>=1.0
Requires-Dist: langchain-mcp-adapters>=0.2
Requires-Dist: mcp<2,>=1.9
Requires-Dist: aiosqlite>=0.20
Requires-Dist: telethon>=1.36
Requires-Dist: aiohttp>=3.10
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: google-play-scraper>=1.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: feedparser>=6.0
Requires-Dist: asyncssh>=2.17
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: cryptography>=42
Requires-Dist: langfuse>=2.0
Provides-Extra: memory
Requires-Dist: mem0ai>=0.1; extra == "memory"
Requires-Dist: sentence-transformers>=5.0; extra == "memory"
Provides-Extra: browser
Requires-Dist: playwright>=1.48; extra == "browser"
Provides-Extra: discord
Requires-Dist: discord.py>=2.0; extra == "discord"
Provides-Extra: tts
Requires-Dist: edge-tts>=6.1; extra == "tts"
Provides-Extra: aso
Requires-Dist: httpx>=0.27; extra == "aso"
Requires-Dist: langgraph>=0.4; extra == "aso"
Requires-Dist: langgraph-checkpoint-sqlite>=2.0; extra == "aso"
Provides-Extra: appstore
Requires-Dist: PyJWT[crypto]>=2.8; extra == "appstore"
Provides-Extra: analytics
Requires-Dist: google-analytics-data>=0.18; extra == "analytics"
Provides-Extra: seo-geo
Requires-Dist: google-api-python-client>=2.140; extra == "seo-geo"
Requires-Dist: google-auth>=2.34; extra == "seo-geo"
Provides-Extra: documents
Requires-Dist: pypdf>=4.0; extra == "documents"
Requires-Dist: python-docx>=1.1; extra == "documents"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Dynamic: license-file

# Kronos Agent OS (KAOS)

[![CI](https://github.com/spyrae/kronos-agent-os/actions/workflows/ci.yml/badge.svg)](https://github.com/spyrae/kronos-agent-os/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/kronos-agent-os.svg)](https://pypi.org/project/kronos-agent-os/)
[![PyPI downloads](https://img.shields.io/pypi/dm/kronos-agent-os.svg)](https://pypi.org/project/kronos-agent-os/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](pyproject.toml)

Self-hosted runtime for durable AI agents that remember, use skills, call MCP tools, run scheduled work, and coordinate optional sub-agents.

KAOS is an agent operating layer:

![KAOS durable agent demo](docs/assets/kaos-durable-agent-demo.gif)

- **Runtime**: local agent loop with CLI, Telegram, Discord, webhook, and cron entry points.
- **Memory**: session history, FTS5 recall, Mem0 vectors, knowledge graph, and sleep-time consolidation.
- **Skills**: workspace-local procedures and references the agent can load on demand.
- **Tool gateway**: MCP tools, custom tools, browser tools, and audit-friendly execution.
- **Automations**: scheduled jobs for digests, monitoring, analytics, and self-improvement.
- **Analytics**: pluggable data sources (Zabbix, Grafana, Sentry, PostHog HogQL, App Store Connect, Supabase, GA4, RevenueCat, LiteLLM, Langfuse, Linear) feeding daily pulse and weekly business reports.
- **Competitor monitoring**: weekly intelligence cycle across App Store, Play Store, blogs, Twitter, press, ProductHunt and job boards with Brave→Exa search fallback.
- **Control room**: dashboard/API surfaces for memory, jobs, tool calls, and system status.
- **Coordination**: optional sub-agent and swarm mode with SQLite arbitration.

The default public posture is local-first and conservative: dynamic tools, dynamic MCP server management, and SSH/server operations are disabled unless explicitly enabled.

## Quickstart

Requirements:

- Python 3.11+
- Node.js 18.18+ for the optional dashboard UI

Install from PyPI:

```bash
pip install kronos-agent-os
kaos demo
```

`kaos demo` runs offline, no LLM key needed. To go further:

```bash
kaos doctor
kaos init personal-operator --role "personal operator for research and tasks"
# edit ~/.kaos/.env or your project .env: at least one real LLM key, or Ollama/local
```

For development or to track `main`:

```bash
git clone https://github.com/spyrae/kronos-agent-os.git
cd kronos-agent-os

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

kaos demo
cp .env.example .env
kaos doctor
```

Bring your own LLM by editing `.env`. The default chain is DeepSeek (with the
top-level orchestrator on Codex CLI), but OpenAI, OpenRouter, Groq, Together,
LiteLLM, Ollama, and arbitrary OpenAI-compatible endpoints can be configured
without code changes. See [LLM Providers](docs/LLM_PROVIDERS.md).

If you work on the dashboard UI, run `nvm use` from the repository root before
`npm install` in `dashboard-ui/`.

For memory features:

```bash
pip install -e ".[dev,memory]"
```

For ASO automation:

```bash
pip install -e ".[dev,aso]"
```

For Telegram:

```bash
python scripts/auth-userbot.py
python -m kronos
```

Docker quickstart starts the safe local dashboard/control room:

```bash
cp .env.example .env
docker compose up --build
```

The Compose ports bind to `127.0.0.1` on the host. The full Telegram/webhook runtime is still `python -m kronos` after credentials are configured.

Dashboard demo state for screenshots and local demos:

![KAOS Control Room dashboard](docs/assets/kaos-dashboard-control-room.svg)

```bash
kaos demo-seed --reset
AGENT_NAME=demo DB_DIR=data/demo DB_PATH=data/demo/session.db SWARM_DB_PATH=data/demo/swarm.db WORKSPACE_PATH=workspaces/demo kaos dashboard
```

The seeded data is deterministic and public-safe: no private Telegram IDs, live memories, tokens, or personal workspace names.

## Mental Model

```mermaid
flowchart LR
    U["User / Cron / Connector"] --> R["KAOS Runtime"]
    R --> M["Memory"]
    R --> S["Skills"]
    R --> G["Tool Gateway"]
    R --> A["Automations"]
    R --> W["Sub-Agent Coordination"]
    G --> MCP["MCP Servers"]
    G --> CT["Custom Tools"]
    A --> R
    R --> D["Dashboard Control Room"]
    M --> D
    G --> D
    A --> D
    W --> D
```

Sub-agent coordination is one subsystem inside KAOS. Each agent can run as a separate process with its own persona, workspace, Telegram account, and local memory while sharing a SQLite coordination ledger.

## Core Commands

```bash
kaos --version       # print installed KAOS version
kaos doctor          # validate local setup and safety defaults
kaos init <name>     # create a local agent workspace
kaos demo            # offline walkthrough, no LLM key required
kaos chat            # local CLI chat without Telegram
kaos chat -p "..."   # one-shot local message
kaos chat --no-memory # local chat without long-term memory
kaos chat --tools    # local CLI chat with configured static MCP tools
kaos dashboard       # start the local dashboard API/UI
kaos demo-seed --reset # seed public-safe dashboard demo data
kaos export --out a.kaos # export this agent as a portable bundle
kaos import a.kaos --dry-run # preview importing a bundle
kaos import-from auto <path> # bring history from ChatGPT/Claude/Obsidian/Telegram/Letta
kaos eval run         # replay golden scenarios (no keys, no network)
kaos eval diff --base origin/main # what did my change move?
kaos policy report    # effective governance posture and value sources
kaos audit verify     # has the audit trail been edited?
kaos swarm report --week # who answered, how well, at what cost
kaos skills search memo  # search configured skill sources
kaos skills install <name> # install with signature + scenario checks
kaos skills verify       # re-check checksums, signatures, versions
kaos skills stats        # which skills are actually used
kaos demo --swarm     # swarm coordination locally: no Telegram, no keys
kaos connect telegram # guided Telegram setup check
kaos templates list  # list bundled agent templates
kaos skills packs    # list bundled skill packs
python -m kronos     # run the Telegram/webhook runtime
```

`kaos demo` is deterministic and runs without Telegram, Docker, or provider keys. Use `kaos demo --live` when you want the same safety gates with a real LLM-backed chat. Demo mode forces conservative defaults for dynamic tools, dynamic MCP, and server ops even if the local environment enables them.

## Configuration

Copy `.env.example` to `.env`. Minimum useful local setup:

```bash
DEEPSEEK_API_KEY=sk-...       # or OPENAI_API_KEY
AGENT_NAME=kronos             # uses workspaces/kronos/
```

Telegram requires:

```bash
TG_API_ID=12345678
TG_API_HASH=abc123...
ALLOWED_USERS=123456789       # comma-separated Telegram user IDs
ALLOW_ALL_USERS=false         # keep false unless this is a private/trusted account
```

Public-safe capability gates:

```bash
ENABLE_DYNAMIC_TOOLS=false
REQUIRE_DYNAMIC_TOOL_SANDBOX=true
ENABLE_MCP_GATEWAY_MANAGEMENT=false
ENABLE_DYNAMIC_MCP_SERVERS=false
ENABLE_SERVER_OPS=false
```

Enable risky capabilities only in trusted local deployments where you understand the tool surface.

## Create Your First Agent

KAOS ships the runtime, templates, and skill packs. You bring the domain.

```bash
kaos templates list
kaos templates install personal-operator personal-demo --force
kaos skills packs
kaos skills install-pack productivity --agent personal-demo --force

AGENT_NAME=personal-demo kaos doctor
AGENT_NAME=personal-demo kaos chat
```

Then edit `workspaces/personal-demo/self/IDENTITY.md`, add domain-specific
skills under `workspaces/personal-demo/self/skills/`, and connect MCP tools as
needed.

## Project Structure

```text
kronos/
  engine.py            # custom ReAct loop
  graph.py             # main runtime pipeline
  bridge.py            # Telethon transport
  cli.py               # kaos doctor/chat/demo
  group_router.py      # group routing and addressing
  swarm_store.py       # SQLite swarm ledger and claim arbitration
  config.py            # Pydantic settings
  agents/              # specialized sub-agents
  memory/              # Mem0, FTS5, knowledge graph, context engine
  skills/              # skill loading and approval tools
  tools/               # MCP, browser, dynamic, server ops, custom tools
  cron/                # scheduled jobs
dashboard/             # API/backend dashboard surfaces
dashboard-ui/          # web control room UI
workspaces/
  _template/           # public starter workspace for kaos init
  <agent>/             # local runtime state, gitignored
templates/
  agents/              # bundled safe agent profiles
  skill-packs/         # bundled reusable skill packs
docs/                  # docs index, runtime, memory, skills, MCP, automations, coordination
```

## Bring Your History

An agent is a persona, a set of skills, and a memory of you — so KAOS makes that
portable instead of locking it in.

```bash
kaos export --out my-agent.kaos            # move or back up an agent
kaos import my-agent.kaos --dry-run        # see exactly what would change
kaos import-from auto ~/chatgpt-export     # start from history you already have
```

Bundles are content-hashed and deterministic, secrets and Telegram sessions are
never included, and imported skills arrive as drafts for review. Importers exist
for ChatGPT, Claude projects, Obsidian vaults, Telegram exports, and Letta agent
files. See [Portability](docs/PORTABILITY.md).

## Behaviour You Can Check

An agent that changes behaviour quietly is worse than one that fails loudly, so
KAOS ships its own CI for agent behaviour.

```bash
kaos eval turns                    # what has this agent actually done?
kaos eval capture --turn <id>      # turn a real turn into a golden scenario
kaos eval run                      # replay the suite: no keys, no network
kaos eval diff --base origin/main  # tools, turns, gating: what moved?
```

Scenarios replay the model turns a real run produced, so tool wiring, call order,
approval gating and budgets stay verifiable even when the prompt changes.
Cassettes cover the other half — byte-stable replay of provider and tool calls.
See [Agent CI](docs/EVALS.md).

## Sub-Agents And Swarm Mode

KAOS Swarm Mode is the optional multi-agent coordination layer inside the broader Agent OS.

- Agents observe the same group message independently.
- Tier-based routing decides whether an agent should respond.
- SQLite `IMMEDIATE` transactions prevent duplicate implicit replies.
- Peer reactions let agents disagree or add perspective without polluting long-term memory.

The org chart is config. `agents.yaml` can declare what an agent `owns`, who it
`escalates_to` after `sla_minutes` of silence, its own `budget_usd_daily`, and
whether answers there need a peer's review (`dissent: require`). All optional —
omit them and routing behaves as it always has.

```bash
kaos demo --swarm            # see arbitration, ownership and escalation locally
kaos swarm report --week     # who answered, how well, at what cost
```

The demo needs no Telegram accounts and no provider keys: it runs three agents on
an in-process bus over a temporary ledger, through the production router.

This is useful for multi-persona group chats and expert panels, but the default KAOS runtime also works as a single durable agent. See [Sub-Agents & Swarm](docs/SWARM.md).

## Skills From Elsewhere

A skill is a markdown procedure the agent follows, so installing one accepts
instructions. `registry.yaml` lists sources and how much each must prove:

```bash
cp registry.example.yaml registry.yaml
kaos skills search memo
kaos skills install decision-memo   # verifies, replays the skill's own scenario
kaos skills verify                  # anything tampered with since?
```

A skill installs **active** only when its source requires signing, a key in
`registry.trusted_keys` signed those exact bytes, and the skill's own offline
scenario did not fail. Anything else lands as a draft with the reason attached —
a failure never deletes anything. Publishing (checksum, signing, shipping a
check) is documented in [Registry](docs/REGISTRY.md).

## Governance

What the agent may do lives in one readable file — capabilities, approvals,
budgets, untrusted-content handling, egress, retention:

```bash
cp policy.example.yaml policy.yaml
kaos policy report        # effective posture, and where each value came from
kaos audit verify         # audit logs are hash-chained; has anything been edited?
```

Precedence is env > policy > default, and the report names the winning source for
every value. An invalid policy stops startup rather than reverting to permissive
defaults. See [Governance](docs/GOVERNANCE.md).

## Safety

KAOS can connect to tools, memory, external services, and scheduled jobs. The public defaults are intentionally conservative:

- Dynamic Python tools are disabled by default.
- Dynamic MCP add/remove/reload is disabled by default.
- Persisted dynamic MCP servers are not loaded by default.
- SSH/server operations are disabled by default.
- Dynamic tool execution requires a Docker sandbox by default.
- Telegram DMs are blocked until `ALLOWED_USERS` is set, unless `ALLOW_ALL_USERS=true`.

For local dynamic-tool experiments, build the sandbox image first:

```bash
scripts/build-sandbox.sh
ENABLE_DYNAMIC_TOOLS=true kaos doctor
```

See [docs/SECURITY.md](docs/SECURITY.md) and [SECURITY.md](SECURITY.md).

## Documentation

- [Roadmap](ROADMAP.md)
- [Landing Page Content](docs/LANDING.md)
- [LLM Providers](docs/LLM_PROVIDERS.md)
- [Demo](docs/DEMO.md)
- [Personal Operator Demo](docs/PERSONAL_OPERATOR_DEMO.md)
- [Swarm Mode Demo](docs/SWARM_DEMO.md)
- [Launch Copy](docs/LAUNCH_COPY.md)
- [v0.1.0 Release Notes Draft](docs/RELEASE_NOTES_v0.1.0.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Security](docs/SECURITY.md)
- [Dashboard](docs/DASHBOARD.md)
- [Memory](docs/MEMORY.md)
- [Portability](docs/PORTABILITY.md)
- [Agent CI](docs/EVALS.md)
- [Governance](docs/GOVERNANCE.md)
- [Skills](docs/SKILLS.md)
- [Cron Jobs](docs/CRON-JOBS.md)
- [Deployment](docs/DEPLOYMENT.md)

## License

MIT
