Fellowship
Multi-bot LLM session orchestration API
Fellowship is an API middleware server that sits between any OpenAI-compatible LLM backend and your project. It manages sessions of AI bots — handling turn-taking, system prompts, conversation flow, and real-time delivery to connected clients.
What it does
- Bot sessions — initialize a group of bots with individual personalities and system prompts
- Autonomous conversations — bots talk to each other without human input
- Human participation — one or more humans (talkers) can join a session alongside bots
- Live observation — observers connect and watch conversations in real time, including mid-session
- Orchestration — an internal LLM call routes turns intelligently across 3+ bots
- History rectification — conversation order stays coherent even when messages arrive mid-generation
Status
Early development. Core structure is in place; implementation is in progress.
Requirements
- Python 3.11+
- An OpenAI-compatible LLM backend (e.g. llama.cpp server, Ollama, OpenAI API)
Getting started
# Clone the repo
git clone https://git.ecoposta.sk/Homer/Fellowship.git
cd Fellowship
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Configure
cp .env.example .env
# Edit .env with your LLM backend URL and model names
# Run the server
uvicorn main:app --reload
API docs available at http://localhost:8000/docs once the server is running.
API overview
POST /v1/session/create Create a session, get a token
GET /v1/session/{token} Session status
DELETE /v1/session/{token} End a session
POST /v1/session/{token}/pause Pause the session loop
POST /v1/session/{token}/resume Resume a paused session
WS /v1/session/{token}/connect WebSocket — chat or observe
GET /v1/session/{token}/stream SSE — observe only
GET /v1/session/{token}/history Full conversation history
Full API reference: http://localhost:8000/docs
Configuration
Copy .env.example to .env and fill in your values:
| Variable | Description |
|---|---|
LLM_BASE_URL |
OpenAI-compatible backend URL |
LLM_API_KEY |
API key (can be a dummy value for local backends) |
DEFAULT_BOT_MODEL |
Default model for bot turns |
DEFAULT_ORCHESTRATOR_MODEL |
Model for orchestrator calls |
MAX_BOTS_PER_SESSION |
Server-side cap on bots per session |
SESSION_TTL_DEFAULT |
Idle session timeout in seconds |
DEBUG |
Enable debug events over WebSocket/SSE |
Project structure
fellowship/
api/ HTTP routes, request/response models, event types
core/ Session loop, turn engine, orchestrator, context, rectifier
llm/ OpenAI-compatible LLM client
store/ In-memory session store, SQLite memory store
hub/ WebSocket/SSE connection hub
tests/
unit/
integration/
docs/
License
TBD