Metadata-Version: 2.4
Name: kairos-agent
Version: 0.2.1
Summary: Stop guessing. Run the right pattern. A CLI for executable agent knowledge.
Project-URL: Homepage, https://github.com/vinothhacks/kairos
Project-URL: Repository, https://github.com/vinothhacks/kairos
Project-URL: Issues, https://github.com/vinothhacks/kairos/issues
Project-URL: Changelog, https://github.com/vinothhacks/kairos/blob/main/CHANGELOG.md
Author-email: vinothhacks <vinoth.nagarajan@solverminds.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,cli,karpathy,llm,mcp,rag,react,reflexion,wiki
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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
Requires-Python: <3.14,>=3.11
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: platformdirs<5.0,>=4.2
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<14.0,>=13.7
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: dev
Requires-Dist: mypy<2.0,>=1.10; extra == 'dev'
Requires-Dist: pip-audit<3.0,>=2.7; extra == 'dev'
Requires-Dist: pytest-cov<7.0,>=5.0; extra == 'dev'
Requires-Dist: pytest<10.0,>=8.4.2; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.5; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2.0,>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

<div align="center">
  <img src="assets/hero.png" alt="kairos" width="600" />
  <h1>kairos</h1>
  <p><strong>Stop guessing. Run the right pattern.</strong></p>
  <p>A CLI for executable agent knowledge.</p>
  <p>
    <a href="https://pypi.org/project/kairos-agent/"><img alt="PyPI" src="https://img.shields.io/pypi/v/kairos-agent.svg?color=5eead4&labelColor=0a0a0f"></a>
    <a href="https://www.python.org/downloads/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/kairos-agent.svg?color=5eead4&labelColor=0a0a0f"></a>
    <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-5eead4?labelColor=0a0a0f"></a>
    <a href="https://github.com/vinothhacks/kairos/actions"><img alt="CI" src="https://github.com/vinothhacks/kairos/workflows/ci/badge.svg"></a>
  </p>
  <p>
    <a href="#install">Install</a> · <a href="#30-second-demo">Demo</a> · <a href="#whats-new-in-v02">What's new in v0.2</a> · <a href="#why-kairos">Why kairos</a> · <a href="#quickstart">Quickstart</a> · <a href="#how-it-works">How it works</a> · <a href="#commands">Commands</a> · <a href="#roadmap">Roadmap</a>
  </p>
</div>

---

## What's new in v0.2

**v0.2.0 closes 45 audit findings** we found by auditing our own v0.1.1. Highlights:

- **`.kairos/config.toml`** parser - tune backend, stale window, default technique without env vars.
- **Plugin runners** via `entry_points(group="kairos.runners")` - `pip install kairos-runner-tot` lands without a fork.
- **Real `wiki_index` cache** - selector + query stop re-walking the filesystem on every call.
- **`kairos doctor`** now actually pings `llm-mcp` instead of hard-coding "ok".
- **`kairos feedback <run-id> --rating N`** - capture quality signal for the runs you care about.
- **Retries + backoff** in `MCPLLMClient` - 3 attempts with exponential backoff on 5xx + connect errors.
- **`KAIROS_DB_HOME`** env var - relocate `kairos.db` outside the repo.
- **`kairos run --json`** + **`--llm-rerank`** - structured output and an optional LLM tie-break.

Full migration notes: [`docs/UPGRADING.md`](docs/UPGRADING.md). Zero breaking changes; `v0.1.x → v0.2.0` is in-place.

## Install

```bash
pip install kairos-agent
```

That's it. Zero API keys. Every model call routes through [llm-mcp](https://github.com/vinothhacks/llm-mcp) so you reuse your existing ChatGPT and Claude sessions.

```bash
# or, with uv
uv tool install kairos-agent
```

```powershell
# Windows
irm https://raw.githubusercontent.com/vinothhacks/kairos/v0.2.0/install.ps1 | iex
```

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/vinothhacks/kairos/v0.2.0/install.sh | sh
```

## 30-second demo

```bash
$ kairos init my-wiki && cd my-wiki

$ kairos run "Search the docs for caching and summarize" --dry
   top-3 techniques for: Search the docs for caching...
   ┌──────┬───────────┬───────┬──────────────────────────────────┐
   │ rank │ technique │ score │ rationale                        │
   ├──────┼───────────┼───────┼──────────────────────────────────┤
   │ 1    │ rag       │ 0.70  │ keyword boost 0.50, overlap x4   │
   │ 2    │ react     │ 0.65  │ keyword boost 0.50, overlap x3   │
   │ 3    │ reflexion │ 0.05  │ overlap x1                       │
   └──────┴───────────┴───────┴──────────────────────────────────┘
```

`kairos` looks at your task, queries its wiki of agent techniques, and tells you which pattern to run: RAG, ReAct, or Reflexion. Then it actually runs it.

## Why kairos

You've read the LLM techniques. CoT, ReAct, Reflexion, ToT, HyDE, rerank — twenty patterns each with a paper, each with a use case, each easy to forget the morning you're three coffees into a real problem.

Most "LLM wikis" turn this into a static reading list. **kairos turns it into a runtime decision.** The wiki *is* the agent's playbook:

- **Ingest** raw sources (papers, transcripts, your own notes) → LLM-curated wiki pages.
- **Query** the wiki with natural language; answers cite real pages with `[[wikilinks]]`.
- **Lint** for contradictions, stale claims, and gaps. The wiki gets smarter with every run.
- **Run** any task — kairos picks the right technique by reading its own wiki, then executes it.

Three patterns ship with working runners (RAG, ReAct, Reflexion). The other 18 are documented and ready to be promoted from doc-only to runnable. **You can extend it.**

## Quickstart

```bash
# 1. Bootstrap a project. Copies 21 seed concept pages.
kairos init my-wiki && cd my-wiki

# 2. Ingest a source.
kairos ingest research/karpathy-llm-wiki-gist.md

# 3. Ask a grounded question.
kairos query "When should I use ReAct over RAG?"

# 4. Lint the wiki.
kairos lint

# 5. Run a task — kairos auto-selects the technique.
kairos run "Search the docs for caching, then summarize"

# 6. Or pick the technique manually.
kairos run "Iteratively refine this paragraph" --technique reflexion
```

Every run logs to `.kairos/kairos.db` (SQLite). Every page lives in plain markdown. Every wikilink survives `git diff`.

## How it works

```mermaid
flowchart LR
    User([User]) --> CLI["typer CLI<br/>cli.py"]
    CLI --> Cfg["config.load_config()<br/>env > .kairos/config.toml > defaults"]
    Cfg --> RunCmd["cli run/query/lint/ingest"]

    RunCmd -->|technique=auto| Selector["select_technique"]
    Selector --> Idx["wiki_index<br/>(SQLite cache)"]
    Idx -.cache miss.-> FS["wiki/ filesystem walk"]
    Selector -->|optional --llm-rerank| Rerank["claude_send tie-break"]
    Selector --> Rank["TechniqueChoice ranking"]

    Rank --> Disp["runners.dispatch<br/>+ entry_points discovery"]
    Disp --> ABC["Runner ABC"]
    ABC --> RAG["RagRunner"]
    ABC --> ReA["ReactRunner"]
    ABC --> Refl["ReflexionRunner"]
    ABC -.plugins.-> Plug["kairos-runner-*"]

    RAG --> Rec["RunRecorder.finish<br/>selected_by + score"]
    ReA --> Rec
    Refl --> Rec

    Rec --> DB[("kairos.db<br/>WAL + busy_timeout 5s")]
    DB --> Runs["runs"]
    DB --> FB["feedback (KAI-035)"]
    DB --> WI["wiki_index"]
    DB --> WR["wiki_relations"]

    CLI -->|backend=mcp| MCP["MCPLLMClient<br/>retries + backoff"]
    MCP --> LLM["llm-mcp server"]
    CLI --> Doc["kairos doctor<br/>real ping"] --> MCP
    CLI --> FBcmd["kairos feedback"] --> FB
```

Three layers, mirroring [Karpathy's LLM Wiki gist](https://gist.github.com/karpathy):

1. **`raw/`** - your immutable inputs (papers, articles, transcripts). Source of truth.
2. **`wiki/`** - LLM-generated, human-curated markdown pages. Lives in git.
3. **`AGENTS.md`** - the schema. Tells future LLM passes how the structure works.

See [`docs/architecture.md`](docs/architecture.md) for the full diagram.

## Commands

| Command | What it does |
|---|---|
| `kairos init [path]` | Bootstrap `AGENTS.md`, `raw/`, `wiki/`, `outputs/`. Seeds 21 concept pages. |
| `kairos ingest <file>` | Read a source, propose new + updated wiki pages, log the diff. |
| `kairos query "<q>"` | Lexically retrieve pages, ask the LLM to synthesize, cite wikilinks. |
| `kairos lint` | Local: orphans, missing concepts, stale pages. LLM: contradictions, gaps. |
| `kairos run "<task>"` | Auto-select technique, dispatch runner, log the run. |
| `kairos run "<task>" --dry` | Show the top-3 candidate techniques without running. |
| `kairos doctor` | Print env diagnostics. |
| `kairos version` | Print version. |

## What ships in v0.1

| | Count | Status |
|---|---|---|
| Concept pages (seed wiki) | 21 | doc-only |
| Runner-backed techniques | 3 | RAG, ReAct, Reflexion |
| Unit tests | 48 | green |
| Backends | 1 | SQLite (Postgres optional) |
| LLM bridge | 1 | `llm-mcp` (no API keys) |

The 21 seed concept pages: rag, react, reflexion, chain-of-thought, tree-of-thoughts, self-consistency, self-refine, constitutional-ai, plan-and-execute, few-shot-prompting, zero-shot-prompting, function-calling, tool-use, prompt-injection, embedding-search, hybrid-search, hyde, rerank, router-agent, memory-buffer, llm-wiki.

## Compared to

| | kairos | LLM-wiki gist | Notion AI | Obsidian + plugins |
|---|---|---|---|---|
| Plain markdown source | yes | yes | no | yes |
| Diff-able in git | yes | yes | no | yes |
| Ingest sources via LLM | yes | yes | partial | with plugins |
| Lint for contradictions | **yes** | manual | no | no |
| Pick technique automatically | **yes** | no | no | no |
| Execute the technique | **yes** | no | no | no |
| Zero API keys (uses MCP) | **yes** | no | no | no |
| CLI-first | yes | no | no | no |

The wedge: **executable wiki, not passive notes.**

## Configuration

```bash
# Where kairos finds llm-mcp (default: localhost:8765)
export KAIROS_MCP_URL="http://localhost:8765"

# Use a stub LLM client for offline tests
export KAIROS_LLM_BACKEND="stub"
```

Per-project config lives in `.kairos/config.toml`. Run `kairos doctor` to see resolved values.

## Roadmap

- **v0.1** *(now)* — 21 seed pages, 3 runners, SQLite logging, MCP bridge.
- **v0.2** — `--fix` for lint, technique outcome scoring (the selector learns from past runs), 5 more runners.
- **v0.3** — Composite techniques (Reflexion-over-ReAct, ToT-with-retrieval), Postgres backend, multi-user wikis.
- **v1.0** — Plugin runners (`pip install kairos-runner-tot`), web preview server.

See `CHANGELOG.md` for what landed in each release.

## Contributing

Found a wiki page that's wrong? Want a new technique runner? PRs welcome. Read `CONTRIBUTING.md` first.

```bash
git clone https://github.com/vinothhacks/kairos
cd kairos
uv pip install -e ".[dev]"
uv run pytest
```

## License

[MIT](LICENSE) © vinothhacks

## Acknowledgements

The wiki pattern is straight out of [Andrej Karpathy's LLM Wiki gist](https://gist.github.com/karpathy). The README structure follows [jcode](https://github.com/1jehuang/jcode) for the install-first / demo-first style. The technique catalog stands on the shoulders of every paper cited in the seed pages.
