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

GPLv3