# KiloStar A distributed multi-agent collaboration system built with Python [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/) [![Ray](https://img.shields.io/badge/Distributed-Ray-0288d1.svg)](https://docs.ray.io/) [![Pydantic-AI](https://img.shields.io/badge/Framework-Pydantic--AI-ff69b4.svg)](https://ai.pydantic.dev/) [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE) [δΈ­ζ–‡](./README.md) | [**Changelog**](./changelogs/CHANGELOG.md) | [**Roadmap**](./changelogs/ROADMAP.md)
--- **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) ```yaml 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 ``` ```bash docker compose up -d ``` Once running: - Web Console: http://localhost:8000 - Ray Dashboard: http://localhost:8265 ### Local Development ```bash # 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 ```bash # 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](LICENSE).