convez.ai
MCP ServerAutomaçãoIntermediário
vinothhacks

Kairos - Seletor Inteligente de Padrões de Agentes

vinothhacks/kairos

Escolhe e executa o padrão IA certo para sua tarefa automaticamente

Ver no GitHub
InicialPluginScore · de 0 a 100

Um MCP server que automatiza a seleção do padrão de agente IA ideal (RAG, ReAct, Reflexion e mais) baseado na tarefa, consultando um wiki curado de 20+ técnicas. Executa o padrão selecionado sem necessidade de chaves API, roteando através de múltiplos backends (Ollama, OpenAI, Anthropic).

Instalação

$npx convez-ai vinothhacks/kairos

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 6 meses
Versão
v0.4.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Determinar qual técnica de agente usar para um problema específico
  • Executar workflows de IA com padrões otimizados (RAG, ReAct, Reflexion)
  • Construir pipelines de agentes sem necessidade de chaves API (modo stub)
  • Explorar e testar diferentes padrões de arquitetura de IA

Veredito

Kairos é uma ferramenta robusta para quem precisa decidir qual padrão de agente IA usar. Bem arquitetado com suporte MCP, múltiplos backends e controles de segurança estritos (Ruff, mypy, Bandit). Recomendado para desenvolvedores experientes que querem eliminar adivinhação ao projetar sistemas de IA.

README

A tradução para o português deste README ainda está na fila.


What's new in v0.4

v0.4.0 replaces the single llm-mcp shim with direct backends and makes kairos an MCP server. Highlights:

  • Direct model backends - stub, ollama, openai, anthropic, and openai_compat.
  • MCP server mode - kairos mcp serve exposes seven tools to Cursor, Claude Desktop, and custom MCP clients.
  • Safer default - KAIROS_LLM_BACKEND defaults to stub; mcp is removed with a clear migration error.
  • Audit gates closed - Ruff, mypy, Bandit, strict pip-audit, Radon, Semgrep, MCP smoke, live Ollama, and KAI2 regression report are required CI checks.

Full migration notes: docs/UPGRADING.md. MCP setup: docs/MCP.md.

Install

pip install kairos-agent

That's it. By default kairos uses the deterministic stub backend. Point it at Ollama, OpenAI, Anthropic, or any OpenAI-compatible server when you want live model calls.

# or, with uv
uv tool install kairos-agent
# Windows
irm https://raw.githubusercontent.com/vinothhacks/kairos/v0.4.0/install.ps1 | iex
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/vinothhacks/kairos/v0.4.0/install.sh | sh

30-second demo

$ 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

# 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

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 --> Providers["LLM providers<br/>stub / ollama / openai / anthropic / compat"]
    Providers --> LLM["model runtime"]
    CLI --> MCPServer["kairos mcp serve<br/>stdio MCP tools"]
    CLI --> Doc["kairos doctor<br/>provider probe"] --> Providers
    CLI --> FBcmd["kairos feedback"] --> FB

Three layers, mirroring Karpathy's LLM Wiki gist:

  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 for the full diagram.

Commands

CommandWhat 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 lintLocal: orphans, missing concepts, stale pages. LLM: contradictions, gaps.
kairos run "<task>"Auto-select technique, dispatch runner, log the run.
kairos run "<task>" --dryShow the top-3 candidate techniques without running.
kairos historyList recent runs from .kairos/kairos.db.
kairos feedback-listList saved feedback rows.
kairos mcp serveServe kairos tools over stdio MCP.
kairos doctorPrint env diagnostics.
kairos versionPrint version.

Current surface

CountStatus
Concept pages (seed wiki)21doc-only
Runner-backed techniques3RAG, ReAct, Reflexion
Tests115+unit, integration, regression
Storage backend1SQLite
LLM providers5stub, Ollama, OpenAI, Anthropic, OpenAI-compatible

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

kairosLLM-wiki gistNotion AIObsidian + plugins
Plain markdown sourceyesyesnoyes
Diff-able in gityesyesnoyes
Ingest sources via LLMyesyespartialwith plugins
Lint for contradictionsyesmanualnono
Pick technique automaticallyyesnonono
Execute the techniqueyesnonono
Local-first model optionyesnonopartial
CLI-firstyesnonono

The wedge: executable wiki, not passive notes.

Configuration

# Default: deterministic stub backend for offline tests
export KAIROS_LLM_BACKEND="stub"

# Local Ollama
export KAIROS_LLM_BACKEND="ollama"
export KAIROS_OLLAMA_MODEL="llama3.1"

# OpenAI / Anthropic
export KAIROS_LLM_BACKEND="openai"
export OPENAI_API_KEY="..."
export KAIROS_OPENAI_MODEL="gpt-4o-mini"

export KAIROS_LLM_BACKEND="anthropic"
export ANTHROPIC_API_KEY="..."

# LM Studio / vLLM / OpenRouter / Ollama OpenAI mode
export KAIROS_LLM_BACKEND="openai_compat"
export KAIROS_LLM_BASE_URL="http://localhost:1234/v1"
export KAIROS_LLM_MODEL="local-model"

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

Roadmap

  • v0.4 (now) — direct providers, kairos mcp serve, required audit gates.
  • v0.5 — remove the compatibility kairos.llm.mcp_client import shim and expand provider cassettes.
  • 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.

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

License

MIT © vinothhacks

Acknowledgements

The wiki pattern is straight out of Andrej Karpathy's LLM Wiki gist. The README structure follows jcode for the install-first / demo-first style. The technique catalog stands on the shoulders of every paper cited in the seed pages.

Ver o original no GitHub

Bom para

Relacionados