# KiloStar An open-source general-purpose multi-agent collaboration platform [![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)
--- ## Overview **KiloStar** is an open-source general-purpose multi-agent collaboration platform that provides a complete capability stack covering model integration, agent orchestration, workflow execution, and plugin extension. The system uses **Ray** for distributed execution, **Pydantic-AI** for type-safe agent development, and exposes a unified API surface through **FastAPI**. The platform supports both cloud API models and locally fine-tuned models, ships with built-in core nodes for multi-agent collaboration (Regulatory, Consciousness, Control, Growth), and provides a **heavy plugin** mechanism that lets users reshape the platform into purpose-built agent applications. > **Current version**: `v0.1.1-alpha` ## Highlights - **Local fine-tuned models as first-class citizens**: Built-in vLLM adapter; locally fine-tuned models are interchangeable with cloud API models at the call site, allowing different agent nodes to bind different local models. - **Heavy plugin mechanism**: Plugins can ship their own frontend pages, tool sets, and API endpoints β€” turning KiloStar into specialized agent applications such as coding assistants, learning helpers, or data analysis tools. - **Multi-agent collaboration core**: Four system node types (Regulatory / Consciousness / Control / Growth) plus dynamically spawned Worker individuals, with task decomposition, scheduling, and supervision built in. - **standalone / distributed dual mode**: Zero-dependency single-machine startup; horizontal scaling on demand. Business code is identical across both modes. - **Private deployment friendly**: Every component runs inside the user's own environment without mandatory third-party dependencies. --- ## ✨ Core Capabilities ### 🧠 Multi-Agent Collaboration - **System node specialization**: Regulatory, Consciousness, Control, and Growth nodes each cover a distinct responsibility - **Worker dynamic spawning**: On-demand creation of Ordinary / Skill / Special Worker individuals - **Strongly-typed communication**: Pydantic-AI constrains LLM output to structured data, eliminating the unstructured-text black box in multi-agent flows ### πŸš€ Distributed Execution - **Ray Actor model**: Cross-process and cross-machine collaboration for high-concurrency workloads - **Heterogeneous resource labels**: `kilostar_node_cpu` / `core` / `gpu` route Workers to the right physical nodes - **Standalone mode**: Zero external dependencies for single-machine startup; shares the same business code as distributed mode ### πŸ”„ Workflow Engine - **pydantic-graph driven**: Directed-graph workflow orchestration with conditional branching and loops - **Cross-process persistence**: PostgreSQL state snapshots enable workflow resume after interruption - **Human-in-the-Loop (HITL)**: Built-in HumanApproval node with idempotent resume semantics ### 🧩 Plugin System - **Tool plugins**: Standard tool calls; MCP protocol support for third-party services - **Skill (compatible with Anthropic Agent Skills spec)**: Installed and parsed via [viceroy](https://github.com/zhaoxi826/viceroy), loaded on demand at runtime - **Heavy plugins (planned)**: Vertical application packages with dedicated UI that reshape KiloStar into specialized platforms ### πŸ›‘οΈ 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 is transmitted via the `Authorization` header, never exposed in URLs ### πŸ“¦ Companion Subprojects | Project | Codename | Purpose | Status | |:--|:--|:--|:--| | [kilostar-viceroy](https://github.com/zhaoxi826/viceroy) | Viceroy | Skill installation and cluster-wide distribution | βœ… Released | | [kilostar-stardomain](./subprojects/stardomain) | Stardomain | Sandbox execution for Skill / plugin scripts | In progress | | [kilostar-thought](https://github.com/zhaoxi826/thought) | Thought | Augmented memory system for agents | In progress | --- ## πŸš€ 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/ # Deprecated (name reserved for future remote-probe node) β”‚ β”‚ β”‚ └── 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).