1 line
8.8 KiB
JSON
1 line
8.8 KiB
JSON
{"repo": "antra-tess/chapterx", "files": {"README.md": {"3ff2a52f43b5756d94626bbf058e041ac08e0ddd": {"t": 1785674436.0713248, "n": 8484, "h": "2075e07c1c68d442", "c": "# ChapterX - Discord Bot Framework\n\nA sophisticated Discord chat bot framework with multi-LLM support, MCP tool integration, and advanced context management.\n\n## Features\n\n- **Multi-Participant Context**: Honest representation of Discord conversations\n- **Multiple LLM Providers**: Anthropic, AWS Bedrock, OpenAI-compatible, Google Gemini\n- **Prefill & Chat Modes**: Full support for both conversation modes\n- **MCP Tool Integration**: Native Model Context Protocol support\n- **Rolling Context**: Efficient prompt caching with rolling message windows\n- **Hierarchical Configuration**: YAML-based config with guild/channel overrides\n- **Image Support**: Automatic image caching and vision input\n- **Advanced Features**: History commands, m commands, dot messages\n\n## Quick Start\n\n### 1. Install Dependencies\n\n```bash\nnpm install\n```\n\n### 2. Configure Environment\n\nCreate a `discord_token` file with your bot token:\n\n```bash\necho \"your-discord-bot-token\" > discord_token\n```\n\nSet environment variables (optional - these have defaults):\n\n```bash\nexport CONFIG_PATH=./config # Default: ./config\nexport TOOLS_PATH=./tools # Default: ./tools\nexport CACHE_PATH=./cache # Default: ./cache\nexport LOG_LEVEL=info # Default: info\n\n# Optional: Enable REST API\nexport API_BEARER_TOKEN=$(openssl rand -hex 32) # Generate secure token\nexport API_PORT=3000 # Default: 3000\n```\n\n**Note:** The bot name is automatically determined from the Discord bot's username. Config is loaded from `config/bots/{discord-username}.yaml`.\n\n#### Optional: REST API\n\nTo enable the REST API, set `API_BEARER_TOKEN`:\n\n```bash\necho \"your-secure-api-token\" > api_token\nexport API_BEARER_TOKEN=$(cat api_token)\n```\n\nThe API will be available at `http://localhost:3000` (or your configured `API_PORT`).\n\n### 3. Create Bot Configuration\n\nCreate `config/bots/your-bot-name.yaml`:\n\n```yaml\nname: Claude # Name used in LLM context\n\nmode: prefill\ncontinuationModel: claude-3-5-sonnet-20241022\ntemperature: 1.0\nmaxTokens: 4096\n\nrecencyWindowMessages: 400 # Optional: max messages\nrecencyWindowCharacters: 100000 # Optional: max characters \nrollingThreshold: 50\n\nincludeImages: true\nmaxImages: 5\n\ntoolsEnabled: true\ntoolOutputVisible: false\n```\n\n### 4. Configure Vendor\n\nCreate `config/shared.yaml`:\n\n**Anthropic:**\n```yaml\nvendors:\n anthropic:\n config:\n anthropic_api_key: \"sk-ant-...\"\n provides:\n - \"claude-3-5-sonnet-*\"\n - \"claude-3-opus-*\"\n - \"claude-sonnet-4-*\"\n```\n\n**OpenAI (or compatible API):**\n```yaml\nvendors:\n openai:\n config:\n openai_api_key: \"sk-...\"\n openai_base_url: \"https://api.openai.com/v1\" # Optional, for compatible APIs\n provides:\n - \"gpt-4o*\"\n - \"gpt-4-turbo*\"\n - \"gpt-3.5-turbo*\"\n```\n\n**Notes on OpenAI provider:**\n- Only supports `mode: chat` (not prefill - OpenAI doesn't allow partial assistant messages)\n- Images not yet supported (different format from Anthropic)\n- For prefill support with OpenAI-compatible APIs, additional providers needed (OpenRouter, completions API)\n\n### 5. Run\n\n```bash\n# Development\nnpm run dev\n\n# Production\nnpm run build\nnpm start\n```\n\n## Documentation\n\n- [Architecture](./architecture.md) - Detailed architecture documentation\n- [Requirements](./requirements.md) - Full functional requirements \n- [Plugins](./docs/plugins.md) - Plugin system documentation\n- [Deployment](./docs/deployment.md) - Production deployment guide\n\n### Key Components\n\n- **Agent Loop**: Main orchestrator\n- **Discord Connector**: Handles all Discord API interactions\n- **Context Builder**: Transforms Discord → participant format\n- **LLM Middleware**: Transforms participant → provider format\n- **Tool System**: MCP integration and JSONL persistence\n- **Config System**: Hierarchical YAML configuration\n\n## Configuration\n\n### Bot Configuration\n\n```yaml\n# Identity\nname: BotName # Name used in LLM context (prefill labels, stop sequences)\n\n# Model\nmode: prefill # or 'chat'\ncontinuationModel: claude-3-5-sonnet-20241022\ntemperature: 1.0\nmaxTokens: 4096\ntopP: 1.0\n\n# Context\nrecencyWindowMessages: 400 # Optional: max messages\nrecencyWindowCharacters: 100000 # Optional: max characters\n# When both specified, whichever limit is reached first is used\nrollingThreshold: 50\n\n# Images\nincludeImages: true\nmaxImages: 5\n\n# Tools\ntoolsEnabled: true\ntoolOutputVisible: false\nmaxToolDepth: 100\n\n# Retry\nllmRetries: 3\ndiscordBackoffMax: 32000\n\n# Misc\nsystemPrompt: \"Optional system prompt\"\nreplyOnRandom: 0\nreplyOnName: false\nmaxQueuedReplies: 1\n```\n\n### Discord Commands\n\n**History Command** (requires authorized role):\n```\n.history botname\n---\nfirst: https://discord.com/channels/.../message_id\nlast: https://discord.com/channels/.../message_id\n```\n\n**Config Command** (must be pinned):\n```\n.config botname\n---\ntemperature: 0.7\nmaxTokens: 2000\n```\n\n**M Commands**:\n- `m continue` - Activate bot without mention\n\n## Debugging & Tracing\n\nThe bot includes a comprehensive tracing system that captures every activation, including Discord context, LLM requests/responses, tool executions, and console logs.\n\n### Trace Web Viewer\n\nStart the local web viewer to browse and search traces:\n\n```bash\n./trace serve\n# Opens at http://localhost:3847\n```\n\nFeatures:\n- **Search by Discord URL**: Paste any Discord message URL to find related traces\n- **Full LLM request/response viewer**: See exactly what was sent to the API\n- **Context transformation details**: Understand how Discord messages became LLM context\n- **Console log filtering**: Filter logs by level (debug, info, warn, error)\n- **Token usage & cost info**: Track API usage per activation\n\n### Trace CLI\n\n```bash\n# List recent traces\n./trace list --limit 10\n\n# Show trace summary\n./trace explain <trace-id>\n\n# View full LLM request\n./trace request <trace-id>\n\n# View full LLM response \n./trace response <trace-id>\n\n# View console logs\n./trace logs <trace-id>\n```\n\n### Trace Files\n\nTraces are stored in `logs/traces/` as JSON files with an index at `logs/traces/index.jsonl` for fast lookups.\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Development mode\nnpm run dev\n\n# Build\nnpm run build\n\n# Lint\nnpm run lint\n\n# Format\nnpm run format\n\n# Test\nnpm test\n```\n\n## Updating Dependencies\n\n### Membrane (LLM Abstraction Layer)\n\nChapterX uses [membrane](https://github.com/antra-tess/membrane) as its LLM abstraction layer. Membrane is installed as a git dependency and won't auto-update with regular `npm install`.\n\n**To update membrane to the latest version:**\n\n```bash\nnpm update membrane\n```\n\nThis will fetch the latest commit from the `main` branch and update your `package-lock.json`.\n\n> **Note:** After updating, you should commit the updated `package-lock.json` to keep your deployment in sync. A future release of membrane will be published to npm for easier version management.\n\n**Check current vs latest version:**\n\n```bash\n# See what you have installed\nnpm ls membrane\n\n# See latest on GitHub\ngit ls-remote https://github.com/antra-tess/membrane.git refs/heads/main | cut -c1-7\n```\n\n## Requirements\n\n- Node.js 20+\n- TypeScript 5.3+\n- Discord bot token (in `discord_token` file)\n- LLM API keys (Anthropic, OpenAI, etc.) (in config files)\n\n## REST API\n\nIf enabled with `API_BEARER_TOKEN`, the bot exposes a REST API for accessing Discord conversation history.\n\n### Endpoints\n\n#### `GET /health`\nHealth check (no auth required)\n\n```bash\ncurl http://localhost:3000/health\n```\n\n#### `POST /api/messages/export`\nExport Discord conversation history\n\n**Authentication:** Bearer token required\n\n**Request Body:**\n```json\n{\n \"last\": \"https://discord.com/channels/GUILD_ID/CHANNEL_ID/MESSAGE_ID\",\n \"first\": \"https://discord.com/channels/GUILD_ID/CHANNEL_ID/MESSAGE_ID\",\n \"recencyWindow\": {\n \"messages\": 400,\n \"characters\": 100000\n }\n}\n```\n\n**Example:**\n```bash\ncurl -X POST http://localhost:3000/api/messages/export \\\n -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"last\": \"https://discord.com/channels/123/456/789\"}'\n```\n\n## Acknowledgements\n\nChapterX is developed to be compatible and interoperable with the [chapter2](https://github.com/joysatisficer/chapter2). Many critical concepts, including the use of Discord as the single source of truth, supporting real-time configuration via pinned Discord messages and other, have been pioneered in chapter2 by [Janus](https://x.com/repligate) and [ampdot](https://x.com/amplifiedamp)/[joysatisficer](https://x.com/joysatisficer).\n\n\n## License\n\nMIT\n\n"}}}} |