KiloStar/README-EN.md

KiloStar

A distributed multi-agent collaboration system built with Python

中文 | Changelog | Roadmap

---

KiloStar is a next-generation distributed multi-agent collaboration system powered by Ray. It adopts a "central oversight + edge execution" heterogeneous cluster model, leveraging large MoE models for high-level reasoning while coordinating fine-tuned lightweight models for efficient task execution. Built on Pydantic-AI with strong typing and a FastAPI async gateway, KiloStar delivers end-to-end automation from requirement decomposition to resource scheduling and execution.

Current version: v0.1.1-alpha

---

✨ Key Features

🧠 Heterogeneous Agent Architecture

• Multi-agent cluster: Built-in Regulatory, Consciousness, Control, and Growth core nodes
• Dynamic Worker spawning: On-demand creation of Ordinary or Skill-type Worker Individuals

🚀 Distributed Performance

• Ray-powered: Cross-process, cross-machine Actor communication for high-concurrency workloads
• Local-first: Deep vLLM integration for private model deployment

🔄 Workflow Engine

• pydantic-graph based: Directed-graph workflow orchestration with conditional branching
• Cross-process persistence: PostgreSQL state snapshots enabling workflow resume after interruption
• Human-in-the-Loop (HITL): Built-in HumanApproval node with idempotent resume semantics

🛡️ Security

• JWT authentication: All API endpoints (including SSE streams) require Bearer Token auth
• Ownership enforcement: Workflow/chat resources are user-bound; cross-user access returns 403
• fetch-based SSE: Token transmitted via Authorization header, never exposed in URLs

---

🚀 Quick Start

Docker Compose (Recommended)

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgrespassword
      POSTGRES_DB: kilostar
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d kilostar"]
      interval: 5s
      timeout: 5s
      retries: 5

  kilostar:
    image: zhaoxi5699/kilostar:v0.1.1alpha
    ports:
      - "8000:8000"
      - "8265:8265"
    depends_on:
      db:
        condition: service_healthy
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgrespassword
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432
      - POSTGRES_DB=kilostar
      - SECRET_KEY=changethiskey12345

docker compose up -d

Once running:

• Web Console: http://localhost:8000
• Ray Dashboard: http://localhost:8265

Local Development

# Backend
uv sync
cp config/.env.example .env   # Configure database and secret key
uv run python main.py

# Frontend
cd frontend && npm install && npm run dev

---

📁 Project Structure

KiloStar/
├── main.py                          # App entrypoint (FastAPI + Ray init)
├── pyproject.toml                   # Python dependencies & metadata
├── Dockerfile / docker-compose.yml  # Container deployment
├── alembic/                         # Database migrations
├── config/                          # Environment config templates
├── kilostar/                        # Backend core package
│   ├── api/                         # FastAPI route layer
│   │   ├── system.py                #   /health system health checks
│   │   ├── workflow.py              #   /workflow CRUD + SSE + resume
│   │   ├── chat.py                  #   /chat session management
│   │   ├── agent.py                 #   /agent Worker management
│   │   └── resource.py              #   /resource Skill/Toolset mgmt
│   ├── core/                        # Core business logic
│   │   ├── individual/              #   Agent node implementations
│   │   │   ├── consciousness_node/  #     Task planning
│   │   │   ├── regulatory_node/     #     Quality oversight
│   │   │   ├── control_node/        #     Routing & dispatch
│   │   │   └── growth_node/         #     Capability expansion
│   │   ├── work/                    #   Work execution layer
│   │   │   ├── workflow/            #     Workflow engine (pydantic-graph)
│   │   │   ├── chat/                #     Chat processing
│   │   │   └── task/                #     Single-task execution
│   │   ├── global_state_machine/    #   Global state (Provider/Config)
│   │   ├── global_workflow_manager/ #   Workflow message queue Actor
│   │   └── postgres_database/       #   PostgreSQL DAO layer
│   ├── adapter/                     # Model adapters (OpenAI/vLLM/...)
│   ├── plugin/                      # Tool plugins
│   │   └── tool_plugin/             #     Tavily / FileReader / Approval
│   ├── utils/                       # Utilities
│   │   ├── access.py                #     JWT authentication
│   │   ├── ray_hook.py              #     Ray Actor handle retrieval
│   │   └── check_user/              #     Role-based authorization
│   ├── worker_cluster/              # Worker cluster management
│   └── worker_individual/           # Worker individual lifecycle
├── frontend/                        # React frontend (Vite + Tailwind)
│   └── src/
│       ├── api/                     #   Axios client + SSE wrapper
│       ├── components/              #   UI components
│       │   ├── Chat/                #     Workflow panel + live graph
│       │   ├── Agent/               #     Worker/Provider management
│       │   ├── Plugin/              #     Skill/Tool configuration
│       │   └── Settings/            #     System settings
│       ├── i18n/                    #   Internationalization (zh/en)
│       ├── store/                   #   Zustand state management
│       └── types/                   #   TypeScript type definitions
├── tests/                           # Test suite (249+ cases)
│   ├── unit/                        #   Unit tests
│   └── integration/                 #   Integration smoke tests
└── docs/                            # Design documents

---

🧪 Testing

# Run all tests
uv run pytest tests -q

# Unit tests only
uv run pytest tests/unit -q

# Integration tests
uv run pytest tests/integration -q

---

📄 License

This project is licensed under the Apache License 2.0.