KiloStar/README-EN.md

KiloStar

An open-source general-purpose multi-agent collaboration platform

中文 | Changelog | Roadmap

---

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, 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	Viceroy	Skill installation and cluster-wide distribution	✅ Released
kilostar-stardomain	Stardomain	Sandbox execution for Skill / plugin scripts	In progress
kilostar-thought	Thought	Augmented memory system for agents	In progress

---

🚀 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/        #     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

# 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.