Add README with project overview and structure

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -0,0 +1,113 @@
+# 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
+
+TBD