114 lines
3.0 KiB
Markdown
114 lines
3.0 KiB
Markdown
# 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](https://github.com/ggerganov/llama.cpp) server, Ollama, OpenAI API)
|
|
|
|
---
|
|
|
|
## Getting started
|
|
|
|
```bash
|
|
# 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
|