Metadata-Version: 2.4
Name: evo-ak
Version: 0.71.0
Summary: Shared tooling for agent harnesses: harness schema, multi-source knowledge graph, Claude Code plugins
Author: maycuatroi
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/maycuatroi1/evo-agents
Keywords: agents,harness,knowledge-graph,mcp,claude-code
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: tzdata>=2024.1
Provides-Extra: test
Requires-Dist: pytest>=9.2; extra == "test"
Requires-Dist: pytest-xdist>=3.6; extra == "test"
Requires-Dist: pytest-timeout>=2.3; extra == "test"
Requires-Dist: ruff>=0.6; extra == "test"
Requires-Dist: httpx>=0.27; extra == "test"
Requires-Dist: moto[server]>=5.1; extra == "test"
Requires-Dist: import-linter>=2.15; extra == "test"
Requires-Dist: basedpyright==1.40.2; extra == "test"
Provides-Extra: graphify
Requires-Dist: graphifyy==0.9.73; extra == "graphify"
Provides-Extra: entities
Requires-Dist: openai>=1.40; extra == "entities"
Provides-Extra: clusters
Requires-Dist: graspologic-native==1.3.1; extra == "clusters"
Provides-Extra: semantic
Requires-Dist: fastembed<0.10,>=0.9; extra == "semantic"
Requires-Dist: numpy>=1.26; extra == "semantic"
Provides-Extra: bench
Requires-Dist: pyarrow>=15; extra == "bench"
Provides-Extra: rank
Requires-Dist: lightgbm>=4.5; extra == "rank"
Requires-Dist: numpy>=1.26; extra == "rank"
Provides-Extra: links
Requires-Dist: numpy>=1.26; extra == "links"
Provides-Extra: ingest
Requires-Dist: markitdown[docx,pdf,pptx,xlsx]>=0.1; extra == "ingest"
Provides-Extra: hub-server
Requires-Dist: fastapi>=0.135; extra == "hub-server"
Requires-Dist: uvicorn[standard]>=0.34; extra == "hub-server"
Requires-Dist: psycopg[binary,pool]>=3.2; extra == "hub-server"
Requires-Dist: psycopg-pool>=3.3; extra == "hub-server"
Requires-Dist: alembic>=1.16; extra == "hub-server"
Requires-Dist: sqlalchemy[asyncio]<2.2,>=2.1.3; extra == "hub-server"
Requires-Dist: pydantic>=2.12; extra == "hub-server"
Requires-Dist: sentry-sdk>=2.20; extra == "hub-server"
Requires-Dist: httpx[http2]>=0.27; extra == "hub-server"
Requires-Dist: boto3==1.42.91; extra == "hub-server"
Requires-Dist: cryptography>=44; extra == "hub-server"
Requires-Dist: procrastinate==3.10.0; extra == "hub-server"
Requires-Dist: croniter>=6.0; extra == "hub-server"
Requires-Dist: evo-ak[graphify]; extra == "hub-server"
Requires-Dist: evo-ak[clusters]; extra == "hub-server"
Requires-Dist: evo-ak[rank]; extra == "hub-server"
Requires-Dist: mcp==2.3.0; extra == "hub-server"
Requires-Dist: sigstore<5,>=4.5; extra == "hub-server"
Requires-Dist: aio-pika<10,>=9.5; extra == "hub-server"
Requires-Dist: redis<9,>=8.1; extra == "hub-server"
Provides-Extra: worker
Requires-Dist: aiohttp>=3.9; extra == "worker"
Requires-Dist: claude-agent-sdk>=0.2.163; extra == "worker"
Requires-Dist: openai-codex>=0.160; extra == "worker"
Dynamic: license-file

# evo-agents

**English** | [Tiếng Việt](README.vi.md)

A shared knowledge base and plugin workspace for AI agent teams.

evo-agents brings your codebases, documents, chats, specifications and business signals into one permission-aware hub, extends that workspace across product roles with plugins, and dispatches verified work to **Claude Code, Codex CLI or opencode** on machines you control.

[Get started](docs/getting-started.md) | [Website](https://agents.omelet.tech) | [Plugin guide](docs/plugins.md) | [Documentation](#documentation)

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/kg-entities-1440-dark.png">
  <img alt="The Knowledge Graph Explorer connecting extracted project entities to source files alongside Business and Development cycle navigation." src="docs/images/kg-entities-1440-light.png">
</picture>

## Project knowledge base on the hub

Every project keeps one shared knowledge base on the hub that serves both people in the browser and agents over MCP.

- **Bring code and non-code sources together.** Index Git repositories (code symbols across about 40 languages, commit history and pull requests), drop `.zip` or `.tar.gz` archives of documents and spreadsheets in the browser (`New project from data` or `Upload data`), include approved SRS use cases, Lean Canvas claims and group chat threads, or connect external wikis and tools. Secrets and API keys are redacted before indexing.
- **Link concepts, specs and code with role-aware visibility.** The graph connects domain concepts and document passages directly to files, functions, plan steps and commits. Every member and agent sees only what their clearance and chat membership allow. Named graphs let you scope each agent to a chosen subset of sources, while scheduled optimization runs evaluate retrieval quality and roll back regressions automatically.
- **Keep versioned docs, memories and direct answers.** Teams write versioned Markdown documents and sandboxed interactive pages in **Docs**, share skills and memories across sessions, and ask questions directly in **Home** chat.

## Workspace extended by plugins

A product team needs more than a queue for code commits. Plugins turn the hub into one shared workspace for business analysts, product managers, strategists, marketers, editors and engineers by slotting pages, specialist agents, graph sources and workflow rules into the project's **Business cycle** and **Development cycle**.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/architecture-dark.svg">
  <img alt="How evo-agents connects project sources, the shared knowledge base, the plugin workspace across product cycles, and execution on your machines." src="docs/images/architecture-light.svg">
</picture>

- **Extend both product cycles.** Built-in and core plugins add living **Lean Canvases** (where claims reach validated only with real evidence and signals), versioned **SRS** specifications reviewed by `@ba`, linked **Tasks** and daily **PM** digests, inbound **CRM** contacts, gated **Marketing** channels, **OKR** trees and **Editorial** pipelines.
- **Core and sandboxed plugins on one model.** Plugins ship in two tiers: **core** modules bundled with the hub, and third-party **isolated** plugins that run in separate OS processes and sandboxed UI frames, acting only within the permissions each project grants ([plugin guide](docs/plugins.md)).
- **Install from trusted markets.** Hubs read decentralized plugin markets on GitHub, verify publisher signatures before installing free releases, and support per-hub licences for commercial plugins ([market guide](docs/market.md)). Teams can scaffold custom domain plugins from the template or with `@builder`.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/project-plugins-1440-dark.png">
  <img alt="Enabled core and isolated plugins contributing pages across a project's Business and Development cycles." src="docs/images/project-plugins-1440-light.png">
</picture>

## Agent systems and verified execution on your machines

Underneath the knowledge base and domain plugins, multi-agent systems and worker daemons turn plans and requests into verified changes on hardware you own.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/agent-system-1440-dark.png">
  <img alt="The visual designer of an agent system wiring Entry, Tech lead, Researcher, Developer, Reviewer, Orchestrator and Curator to named knowledge graphs." src="docs/images/agent-system-1440-light.png">
</picture>

- **Wire multi-agent systems visually.** Connect an entry point, specialist agents, an **Orchestrator** that manages queues and stalled plans, a nightly **Curator** that proposes and tests workspace improvements, and named knowledge graphs. Each agent runs on its own dedicated worker and quota pool.
- **Hand off whole plans with re-verified checks.** Describe a change on the **Plans** page, for example:
  > Add saved carts to checkout. Cover the API and frontend, and include tests for restoring a cart after sign-in.

  An agent drafts the steps and checks; once started, a worker runs each step in an isolated Git worktree using **Claude Code, Codex CLI or opencode**, re-runs its verification commands before marking it done, and pushes commits on the plan's branch.
- **Keep credentials sealed and approvals in your hands.** Store model subscriptions, API keys and Git tokens on the hub as sealed secrets leased per run. Your autonomy settings pause a run only on decisions that require human approval in the **Inbox** or on Telegram.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/plan-run-1440-dark.png">
  <img alt="A plan run reporting verified test results and pausing with structured options for a protected deployment change." src="docs/images/plan-run-1440-light.png">
</picture>

## Quick start

**Join or host a hub.** Request an [invite](https://github.com/maycuatroi1/evo-agents/issues/new?template=invite.yml), sign in to your team's hub, or [host one on a single machine](docs/self-host.md). Install Python 3.11+ and [uv](https://docs.astral.sh/uv/), then sign in:

```sh
uv tool install 'evo-ak[graphify,worker]'
evo-agents hub login --url https://hub.example.org
```

Replace `https://hub.example.org` with your hub's URL. From there you can:

- **Start from documents or spreadsheets** in the browser with **New project from data** (`/projects/new`), dropping a `.zip` or `.tar.gz` archive to build a searchable knowledge base without setting up a repository first ([guide](docs/getting-started.md#build-a-project-knowledge-base)).
- **Register repositories and connect a worker** with `evo-agents harness init`, `evo-agents hub project register` and `evo-agents worker join` following the [getting started guide](docs/getting-started.md#run-your-first-plan). Workers run on macOS, Linux, or Windows under WSL.

**Connect your terminal coding agent.** Install the client plugins so interactive sessions read and write hub plans, memories and the knowledge graph over MCP, spool oversized tool outputs locally, and attach call-graph hints after `grep`:

```sh
# Claude Code
claude plugin marketplace add https://github.com/maycuatroi1/evo-agents
claude plugin install evo-hub@evo-agents
claude plugin install evo-kg@evo-agents

# Codex CLI
codex plugin marketplace add https://github.com/maycuatroi1/evo-agents
codex plugin add evo-hub@evo-agents
```

The PyPI distribution is `evo-ak` and the CLI command is `evo-agents`. evo-agents is **pre-1.0**: commands, APIs and schemas can change between releases. Check the [roadmap](docs/roadmap.md) for current status.

## Documentation

| Topic | Guide |
| --- | --- |
| Set up a project, upload data and run a plan | [Getting started](docs/getting-started.md) |
| Configure knowledge sources and query tools | [Graph setup](docs/kg-setup.md), [query reference](docs/kg.md), [evaluation](docs/kg-eval.md) |
| Build, isolate, sign and publish plugins | [Plugin protocol and host](docs/plugins.md), [Plugin market](docs/market.md) |
| Product cycle workflows (Canvas, SRS, Tasks, Loop) | [Problems](docs/problems.md), [Canvas](docs/canvas-plugin.md), [SRS](docs/srs-plugin.md), [Tasks](docs/tasks-plugin.md), [Loop](docs/loop.md) |
| Run workers, manage credentials and set autonomy | [Operations](docs/operations.md), [workers](docs/workers.md), [credentials](docs/credentials.md), [autonomy](docs/autonomy.md) |
| Self-host or deploy a branded client hub | [Single server](docs/self-host.md), [hub deployment](docs/hub-deployment.md) |
| Contribute or report a security issue | [Contributing](CONTRIBUTING.md), [Security policy](SECURITY.md) |

Agent instructions and MCP reference live in [AGENTS.md](AGENTS.md) and the [agent guide](docs/agents.md).

## License

[Apache-2.0](LICENSE).
