agent-forge-installer 0.1.0__tar.gz

agent_forge_installer-0.1.0/PKG-INFO

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: agent-forge-installer
+Version: 0.1.0
+Summary: AgentForge — multi-agent Telegram bot framework powered by Claude Code
+Author: Martin Rancourt
+License: MIT
+Project-URL: Homepage, https://github.com/Martin-Rancourt/agentforge
+Project-URL: Repository, https://github.com/Martin-Rancourt/agentforge
+Project-URL: Bug Tracker, https://github.com/Martin-Rancourt/agentforge/issues
+Keywords: telegram,bot,ai,claude,multi-agent,framework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: http
+Requires-Dist: requests>=2.28; extra == "http"
+Provides-Extra: voice
+Requires-Dist: faster-whisper>=1.0; extra == "voice"
+Provides-Extra: full
+Requires-Dist: requests>=2.28; extra == "full"
+Requires-Dist: faster-whisper>=1.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# AgentForge
+
+A reusable framework for building multi-agent Telegram bots powered by Claude AI.
+
+**Zero dependencies** by default — runs on Python 3.10+ stdlib. Optional extras for voice transcription and faster HTTP.
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/Martin-Rancourt/AgentForge.git
+cd AgentForge
+./install.sh
+
+# Configure
+nano .env                    # Add your Telegram bot token
+nano bot/config.json         # Add your chat IDs
+
+# Create agents
+agentforge agent create assistant --model sonnet --thread-id 11
+agentforge agent create researcher --model opus --thread-id 12
+
+# Run
+agentforge bot
+```
+
+## How It Works
+
+AgentForge turns a **Telegram Supergroup with Forum Topics** into a multi-agent workspace. Each topic routes to a different Claude-powered agent with its own identity, model, and memory.
+
+```
+Telegram Topic (thread_id: 12)
+  → telegram_adapter.py (long-polling)
+  → message_router.py (resolve agent config)
+  → claude_runner.py (invoke Claude CLI with agent's soul.md)
+  → Response sent back to Telegram
+```
+
+### Message Flow
+
+1. Bot polls Telegram for new messages
+2. `message_thread_id` determines which agent handles the message
+3. Conversation history is loaded from SQLite (configurable context window)
+4. Claude Code CLI is invoked with the agent's `soul.md` as system prompt
+5. Response is stored in SQLite and sent back to Telegram
+
+## Architecture
+
+```
+agentforge/
+├── src/agentforge/
+│   ├── telegram_adapter.py   # Main bot — polling, routing, sending
+│   ├── claude_runner.py      # Claude Code CLI subprocess wrapper
+│   ├── message_router.py     # Thread → agent config resolution
+│   ├── config.py             # Typed config loader (dataclasses)
+│   ├── memory_manager.py     # SQLite + FTS5 conversation database
+│   ├── vault.py              # Structured memory store (per-agent)
+│   ├── voice.py              # Voice note transcription (optional)
+│   ├── http_client.py        # Dual-stack: requests or urllib
+│   └── cli/                  # CLI commands (bot, agent, memory, init, vault)
+├── scripts/                   # Bash utilities
+│   ├── telegram_send.sh      # Send messages to topics (with dedup)
+│   ├── heartbeat.sh          # Proactive task runner (cron)
+│   ├── healthcheck.sh        # Daily system health check
+│   ├── agent_task.sh         # Cross-agent task delegation
+│   ├── log_action.sh         # Action logging (Google Sheets + local)
+│   └── memory_consolidation.sh  # Weekly memory merge
+├── tests/                     # Pytest suite (49 tests)
+├── install.sh                # One-liner bootstrap
+└── pyproject.toml            # Package metadata
+```
+
+## CLI Reference
+
+### `agentforge bot`
+
+Start the Telegram bot.
+
+```bash
+agentforge bot [--config path/to/config.json]
+```
+
+### `agentforge agent`
+
+Manage agents declaratively.
+
+```bash
+# Create — scaffolds soul.md, memory.md, daily/ directory
+agentforge agent create <name> --model <model> --thread-id <id>
+
+# List all configured agents
+agentforge agent list
+
+# Remove an agent (--keep-files to preserve files on disk)
+agentforge agent remove <name> [--keep-files]
+```
+
+**Models:** `sonnet` (fast, balanced), `opus` (strongest reasoning), `haiku` (fastest, cheapest)
+
+### `agentforge memory`
+
+Query the conversation database.
+
+```bash
+agentforge memory search "deployment error"    # Full-text search (FTS5)
+agentforge memory recent 50                     # Last 50 messages
+agentforge memory stats                         # Database statistics
+```
+
+### `agentforge vault`
+
+Structured memory store — facts, preferences, and knowledge per agent.
+
+```bash
+agentforge vault write --agent victor --category knowledge --title "API design" --content "..."
+agentforge vault search "deployment"
+agentforge vault list --agent archie
+```
+
+### `agentforge init`
+
+Bootstrap a new instance from scratch.
+
+```bash
+agentforge init [--dir /path/to/instance]
+```
+
+Creates: `bot/`, `agents/`, `data/`, `logs/`, `memory/`, `skills/`, `config.json`, `.env`
+
+## Configuration
+
+### `bot/config.json`
+
+```jsonc
+{
+  "telegram": {
+    "token_env_var": "AGENTFORGE_TELEGRAM_TOKEN",  // env var name holding the token
+    "allowed_chat_ids": [123456789],                // whitelist
+    "group_chat_id": -100123456789,                 // supergroup ID
+    "topics": {                                      // named topic shortcuts
+      "general": 11,
+      "dev": 12
+    }
+  },
+  "claude": {
+    "model": "sonnet",          // default model
+    "max_budget_usd": 1.0       // per-invocation spend cap
+  },
+  "memory": {
+    "context_messages": 10      // messages included as context
+  },
+  "threads": {
+    "11": { "name": "assistant", "model": "sonnet", "context_messages": 10 },
+    "12": { "name": "researcher", "model": "opus",  "context_messages": 15 }
+  }
+}
+```
+
+### `.env`
+
+```bash
+AGENTFORGE_TELEGRAM_TOKEN=your_bot_token_here
+AGENTFORGE_ROOT=/path/to/instance    # defaults to /home/clawdia
+```
+
+## Multi-Agent System
+
+Each agent gets its own identity via a `soul.md` file:
+
+```
+agents/
+├── victor/
+│   ├── soul.md        # Personality, role, instructions
+│   ├── memory.md      # Long-term consolidated memory
+│   └── daily/         # Daily learnings (YYYY-MM-DD.md)
+├── archie/
+└── catherine/
+```
+
+The `soul.md` is passed as `--system-prompt` to Claude, completely overriding the default identity. Agents can:
+
+- Have different Claude models (opus for complex reasoning, haiku for quick tasks)
+- Maintain separate conversation histories and context windows
+- Store per-agent structured memory in the vault
+- Delegate tasks to each other via `agent_task.sh`
+
+### Project Topics
+
+Beyond agent topics, you can configure **project topics** where multiple agents collaborate:
+
+```json
+"project_topics": {
+  "42": {
+    "label": "🏗 Dev",
+    "agents": ["victor", "archie"],
+    "default_agent": "victor"
+  }
+}
+```
+
+Use `@agentname` mentions to address a specific agent in a shared topic.
+
+## Scripts
+
+| Script | Purpose | Trigger |
+|--------|---------|---------|
+| `telegram_send.sh` | Send messages to topics | Manual / cross-agent |
+| `heartbeat.sh` | Run proactive tasks from `heartbeat.md` | Cron |
+| `healthcheck.sh` | System health report | Cron (daily) |
+| `agent_task.sh` | Delegate tasks between agents | Inter-agent |
+| `log_action.sh` | Log external actions to Sheets + file | After side-effects |
+| `memory_consolidation.sh` | Merge daily logs → `memory.md` | Cron (weekly) |
+
+### Dedup
+
+`telegram_send.sh` has built-in deduplication: identical messages to the same topic within 60 seconds are silently dropped.
+
+## Memory System
+
+AgentForge provides three layers of memory:
+
+| Layer | Storage | Purpose |
+|-------|---------|---------|
+| **Conversations** | SQLite + FTS5 | Full message history, searchable |
+| **Vault** | SQLite + FTS5 | Structured facts/preferences per agent |
+| **Files** | Markdown | `soul.md` (identity), `memory.md` (long-term), `daily/` (learnings) |
+
+The weekly `memory_consolidation.sh` script merges daily learnings into each agent's `memory.md`.
+
+## Dependencies
+
+**Core:** Python 3.10+ stdlib only (no pip install required for basic operation)
+
+**Optional extras:**
+
+```bash
+pip install agentforge[full]    # requests + faster-whisper
+pip install agentforge[dev]     # pytest + pytest-cov
+```
+
+| Extra | Package | Purpose |
+|-------|---------|---------|
+| `full` | `requests>=2.28` | Faster HTTP client (falls back to urllib) |
+| `full` | `faster-whisper>=1.0` | Voice note transcription |
+| `dev` | `pytest>=7` | Test runner |
+| `dev` | `pytest-cov` | Coverage reports |
+
+## External Requirements
+
+- **Claude Code CLI** — must be installed at `$AGENTFORGE_ROOT/.local/bin/claude`
+- **Telegram Bot** — create one via [@BotFather](https://t.me/BotFather), enable Forum Topics in your supergroup
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest                      # Run all 49 tests
+pytest --cov=agentforge     # With coverage
+```
+
+Tests cover: config validation, message routing, memory manager, vault operations.
+
+## Releases
+
+This project uses [release-please](https://github.com/googleapis/release-please) for automated releases:
+
+1. Use **conventional commits** (`feat:`, `fix:`, `docs:`, `chore:`, etc.)
+2. Release-please accumulates changes and opens a **Release PR** with version bump + changelog
+3. Merge the Release PR → GitHub Release + git tag created automatically
+
+## License
+
+MIT

agent_forge_installer-0.1.0/README.md

@@ -0,0 +1,273 @@
+# AgentForge
+
+A reusable framework for building multi-agent Telegram bots powered by Claude AI.
+
+**Zero dependencies** by default — runs on Python 3.10+ stdlib. Optional extras for voice transcription and faster HTTP.
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/Martin-Rancourt/AgentForge.git
+cd AgentForge
+./install.sh
+
+# Configure
+nano .env                    # Add your Telegram bot token
+nano bot/config.json         # Add your chat IDs
+
+# Create agents
+agentforge agent create assistant --model sonnet --thread-id 11
+agentforge agent create researcher --model opus --thread-id 12
+
+# Run
+agentforge bot
+```
+
+## How It Works
+
+AgentForge turns a **Telegram Supergroup with Forum Topics** into a multi-agent workspace. Each topic routes to a different Claude-powered agent with its own identity, model, and memory.
+
+```
+Telegram Topic (thread_id: 12)
+  → telegram_adapter.py (long-polling)
+  → message_router.py (resolve agent config)
+  → claude_runner.py (invoke Claude CLI with agent's soul.md)
+  → Response sent back to Telegram
+```
+
+### Message Flow
+
+1. Bot polls Telegram for new messages
+2. `message_thread_id` determines which agent handles the message
+3. Conversation history is loaded from SQLite (configurable context window)
+4. Claude Code CLI is invoked with the agent's `soul.md` as system prompt
+5. Response is stored in SQLite and sent back to Telegram
+
+## Architecture
+
+```
+agentforge/
+├── src/agentforge/
+│   ├── telegram_adapter.py   # Main bot — polling, routing, sending
+│   ├── claude_runner.py      # Claude Code CLI subprocess wrapper
+│   ├── message_router.py     # Thread → agent config resolution
+│   ├── config.py             # Typed config loader (dataclasses)
+│   ├── memory_manager.py     # SQLite + FTS5 conversation database
+│   ├── vault.py              # Structured memory store (per-agent)
+│   ├── voice.py              # Voice note transcription (optional)
+│   ├── http_client.py        # Dual-stack: requests or urllib
+│   └── cli/                  # CLI commands (bot, agent, memory, init, vault)
+├── scripts/                   # Bash utilities
+│   ├── telegram_send.sh      # Send messages to topics (with dedup)
+│   ├── heartbeat.sh          # Proactive task runner (cron)
+│   ├── healthcheck.sh        # Daily system health check
+│   ├── agent_task.sh         # Cross-agent task delegation
+│   ├── log_action.sh         # Action logging (Google Sheets + local)
+│   └── memory_consolidation.sh  # Weekly memory merge
+├── tests/                     # Pytest suite (49 tests)
+├── install.sh                # One-liner bootstrap
+└── pyproject.toml            # Package metadata
+```
+
+## CLI Reference
+
+### `agentforge bot`
+
+Start the Telegram bot.
+
+```bash
+agentforge bot [--config path/to/config.json]
+```
+
+### `agentforge agent`
+
+Manage agents declaratively.
+
+```bash
+# Create — scaffolds soul.md, memory.md, daily/ directory
+agentforge agent create <name> --model <model> --thread-id <id>
+
+# List all configured agents
+agentforge agent list
+
+# Remove an agent (--keep-files to preserve files on disk)
+agentforge agent remove <name> [--keep-files]
+```
+
+**Models:** `sonnet` (fast, balanced), `opus` (strongest reasoning), `haiku` (fastest, cheapest)
+
+### `agentforge memory`
+
+Query the conversation database.
+
+```bash
+agentforge memory search "deployment error"    # Full-text search (FTS5)
+agentforge memory recent 50                     # Last 50 messages
+agentforge memory stats                         # Database statistics
+```
+
+### `agentforge vault`
+
+Structured memory store — facts, preferences, and knowledge per agent.
+
+```bash
+agentforge vault write --agent victor --category knowledge --title "API design" --content "..."
+agentforge vault search "deployment"
+agentforge vault list --agent archie
+```
+
+### `agentforge init`
+
+Bootstrap a new instance from scratch.
+
+```bash
+agentforge init [--dir /path/to/instance]
+```
+
+Creates: `bot/`, `agents/`, `data/`, `logs/`, `memory/`, `skills/`, `config.json`, `.env`
+
+## Configuration
+
+### `bot/config.json`
+
+```jsonc
+{
+  "telegram": {
+    "token_env_var": "AGENTFORGE_TELEGRAM_TOKEN",  // env var name holding the token
+    "allowed_chat_ids": [123456789],                // whitelist
+    "group_chat_id": -100123456789,                 // supergroup ID
+    "topics": {                                      // named topic shortcuts
+      "general": 11,
+      "dev": 12
+    }
+  },
+  "claude": {
+    "model": "sonnet",          // default model
+    "max_budget_usd": 1.0       // per-invocation spend cap
+  },
+  "memory": {
+    "context_messages": 10      // messages included as context
+  },
+  "threads": {
+    "11": { "name": "assistant", "model": "sonnet", "context_messages": 10 },
+    "12": { "name": "researcher", "model": "opus",  "context_messages": 15 }
+  }
+}
+```
+
+### `.env`
+
+```bash
+AGENTFORGE_TELEGRAM_TOKEN=your_bot_token_here
+AGENTFORGE_ROOT=/path/to/instance    # defaults to /home/clawdia
+```
+
+## Multi-Agent System
+
+Each agent gets its own identity via a `soul.md` file:
+
+```
+agents/
+├── victor/
+│   ├── soul.md        # Personality, role, instructions
+│   ├── memory.md      # Long-term consolidated memory
+│   └── daily/         # Daily learnings (YYYY-MM-DD.md)
+├── archie/
+└── catherine/
+```
+
+The `soul.md` is passed as `--system-prompt` to Claude, completely overriding the default identity. Agents can:
+
+- Have different Claude models (opus for complex reasoning, haiku for quick tasks)
+- Maintain separate conversation histories and context windows
+- Store per-agent structured memory in the vault
+- Delegate tasks to each other via `agent_task.sh`
+
+### Project Topics
+
+Beyond agent topics, you can configure **project topics** where multiple agents collaborate:
+
+```json
+"project_topics": {
+  "42": {
+    "label": "🏗 Dev",
+    "agents": ["victor", "archie"],
+    "default_agent": "victor"
+  }
+}
+```
+
+Use `@agentname` mentions to address a specific agent in a shared topic.
+
+## Scripts
+
+| Script | Purpose | Trigger |
+|--------|---------|---------|
+| `telegram_send.sh` | Send messages to topics | Manual / cross-agent |
+| `heartbeat.sh` | Run proactive tasks from `heartbeat.md` | Cron |
+| `healthcheck.sh` | System health report | Cron (daily) |
+| `agent_task.sh` | Delegate tasks between agents | Inter-agent |
+| `log_action.sh` | Log external actions to Sheets + file | After side-effects |
+| `memory_consolidation.sh` | Merge daily logs → `memory.md` | Cron (weekly) |
+
+### Dedup
+
+`telegram_send.sh` has built-in deduplication: identical messages to the same topic within 60 seconds are silently dropped.
+
+## Memory System
+
+AgentForge provides three layers of memory:
+
+| Layer | Storage | Purpose |
+|-------|---------|---------|
+| **Conversations** | SQLite + FTS5 | Full message history, searchable |
+| **Vault** | SQLite + FTS5 | Structured facts/preferences per agent |
+| **Files** | Markdown | `soul.md` (identity), `memory.md` (long-term), `daily/` (learnings) |
+
+The weekly `memory_consolidation.sh` script merges daily learnings into each agent's `memory.md`.
+
+## Dependencies
+
+**Core:** Python 3.10+ stdlib only (no pip install required for basic operation)
+
+**Optional extras:**
+
+```bash
+pip install agentforge[full]    # requests + faster-whisper
+pip install agentforge[dev]     # pytest + pytest-cov
+```
+
+| Extra | Package | Purpose |
+|-------|---------|---------|
+| `full` | `requests>=2.28` | Faster HTTP client (falls back to urllib) |
+| `full` | `faster-whisper>=1.0` | Voice note transcription |
+| `dev` | `pytest>=7` | Test runner |
+| `dev` | `pytest-cov` | Coverage reports |
+
+## External Requirements
+
+- **Claude Code CLI** — must be installed at `$AGENTFORGE_ROOT/.local/bin/claude`
+- **Telegram Bot** — create one via [@BotFather](https://t.me/BotFather), enable Forum Topics in your supergroup
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest                      # Run all 49 tests
+pytest --cov=agentforge     # With coverage
+```
+
+Tests cover: config validation, message routing, memory manager, vault operations.
+
+## Releases
+
+This project uses [release-please](https://github.com/googleapis/release-please) for automated releases:
+
+1. Use **conventional commits** (`feat:`, `fix:`, `docs:`, `chore:`, etc.)
+2. Release-please accumulates changes and opens a **Release PR** with version bump + changelog
+3. Merge the Release PR → GitHub Release + git tag created automatically
+
+## License
+
+MIT

agent_forge_installer-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-forge-installer"
+version = "0.1.0"
+description = "AgentForge — multi-agent Telegram bot framework powered by Claude Code"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Martin Rancourt" },
+]
+keywords = ["telegram", "bot", "ai", "claude", "multi-agent", "framework"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = []
+# All core dependencies are Python stdlib (json, sqlite3, subprocess, threading, etc.)
+# External dependencies are optional — see [project.optional-dependencies] below.
+
+[project.urls]
+Homepage = "https://github.com/Martin-Rancourt/agentforge"
+Repository = "https://github.com/Martin-Rancourt/agentforge"
+"Bug Tracker" = "https://github.com/Martin-Rancourt/agentforge/issues"
+
+[project.optional-dependencies]
+# Faster HTTP client (falls back to urllib.request if not installed)
+http = ["requests>=2.28"]
+# Voice note transcription support
+voice = ["faster-whisper>=1.0"]
+# Full install: all optional runtime deps
+full = ["requests>=2.28", "faster-whisper>=1.0"]
+# Dev/test tools
+dev = ["pytest>=7", "pytest-cov"]
+
+[project.scripts]
+agentforge = "agentforge.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error::DeprecationWarning"]

agent_forge_installer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+