Skip to content

README.md

Latest commit

 

History

History
101 lines (84 loc) · 4.35 KB

README.md

File metadata and controls

101 lines (84 loc) · 4.35 KB
Raw

Alt text

Vortex Agent

Autonomous, local-first AI agent platform with a council of specialized agents, persistent memory, knowledge graph, governance engine, and sovereign self-management.

Architecture

vortex-agent/
├── backend/                 # FastAPI backend (Python)
│   └── app/
│       ├── main.py          # App entry: CORS, router mounting
│       ├── models.py        # SQLAlchemy models (User, Agent, Task, Memory, Graph, ...)
│       ├── api/v1/          # HTTP endpoints (prefix /api/v1)
│       ├── core/            # memory_system, orchestration
│       ├── council/         # multi-agent deliberation
│       ├── governance/      # policy compliance checks
│       ├── sovereign/       # self-management engine
│       ├── knowledge/       # knowledge graph
│       ├── evolution/       # improvement proposals
│       ├── tools/           # tool registry
│       └── observability/   # tracing
├── frontend/                # React 18 + Vite + Tauri 2 desktop app
│   └── src-tauri/           # Rust shell (com.vortex.agent)
├── cli.py                   # Zero-dependency CLI (stdlib only)
└── run_backend.py           # Start backend on :8000 (uvicorn, reload)

Quick Start

Backend

python run_backend.py          # serves http://localhost:8000
curl http://localhost:8000/api/v1/health

CLI

Zero-dependency — uses only Python stdlib (argparse + urllib). Point it at the backend with --host (default http://localhost:8000).

python cli.py status                     # backend health
python cli.py agents                     # list agents
python cli.py chat "summarize today"     # chat message
python cli.py orchestrate "goal text"    # multi-agent goal
python cli.py task <task_id>             # task status
python cli.py council "topic"            # council deliberation
python cli.py memory add "note"          # store memory
python cli.py memory recall "query"      # recall memory
python cli.py memory context             # full memory context
python cli.py graph nodes                # knowledge graph nodes
python cli.py graph neighbors <id>       # graph neighbors
python cli.py governance check "action"  # compliance check
python cli.py governance logs            # governance log
python cli.py sovereign status           # sovereign state
python cli.py sovereign objectives a b   # set objectives
python cli.py tools list                 # tool registry
python cli.py tools run <tool> --arg k=v # execute tool
python cli.py evolution propose "idea"   # evolution proposal
python cli.py evolution candidates       # pending candidates
python cli.py benchmarks                 # benchmark results
python cli.py trace <task_id>            # observability trace

Desktop App

cd frontend
npm install
npm run tauri:build        # produces MSI + NSIS + standalone exe

API Surface

All endpoints under /api/v1 (the router declares the prefix itself — do not add it again in include_router):

Method Path Purpose
GET /health Health check
POST /chat Chat message
POST /orchestrate Multi-agent orchestration
GET /tasks/{task_id} Task status
POST /council/deliberate Council deliberation
POST /memory/add, /memory/recall Memory store/recall
GET /memory/context Full memory context
POST/GET /graph/nodes, /graph/edges, /graph/neighbors Knowledge graph
POST /governance/check Compliance check
GET /governance/logs Governance log
GET /sovereign/status Sovereign status
POST /sovereign/objectives Set objectives
GET /tools, POST /tools/execute Tool registry
POST /evolution/propose, GET /evolution/candidates Evolution
GET /benchmarks Benchmarks
GET /observability/trace Trace

Known Notes

  • Workspace isolation: src-tauri/Cargo.toml declares its own [workspace] root so Cargo does not inherit a parent-directory workspace (~/Cargo.toml) that may reference uncloned submodules.
  • Data: SQLite via SQLAlchemy; VORTEX_HOME env var overrides the data directory (default backend/vortex-data/).