# 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