forumkit 0.1.0__tar.gz

forumkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Type check
+        run: mypy forumkit/ --strict
+
+      - name: Lint
+        run: ruff check forumkit/ tests/
+
+      - name: Run unit tests
+        run: pytest tests/unit/ -v --tb=short
+
+      - name: Run integration tests
+        run: pytest tests/integration/ -v --tb=short -m integration --maxfail=1
+        continue-on-error: true
+        env:
+          REDIS_URL: redis://localhost:6379
+          PG_DSN: postgresql://postgres:postgres@localhost:5432/test
+          QDRANT_URL: http://localhost:6333

forumkit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

forumkit-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment
+.env
+.venv
+env/
+venv/
+
+# OS
+.DS_Store
+.AppleDouble
+.LSOverride
+*.log
+
+# Project-specific
+.venv/
+dist/

forumkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.1.0] - 2026-04-02
+
+### Added
+- Structured debate protocol: fan-out → challenge → rebuttal → consensus scoring → synthesize
+- Consensus scoring with dissent tracking and unanimity anomaly detection
+- Role-gated agent hierarchy: HEAD, LEAD, SENIOR, JUNIOR roles with LLM-calling restrictions
+- Memory backends: Redis (working memory), PostgreSQL (episodic), Qdrant (semantic)
+- Async orchestration with LiteLLM tool-calling wrapper
+- Prompt injection defense: NFKC normalization + BiDi character stripping + pattern redaction
+- 59 unit tests with full mypy --strict compliance
+- Comprehensive API documentation and examples
+- GitHub Actions CI/CD workflow (pytest + mypy + ruff)
+
+### Documentation
+- README with 5-minute quickstart
+- API reference documenting all public types
+- Concepts guide explaining the debate protocol
+- Working example: simple_debate.py
+
+[0.1.0]: https://github.com/vinitpai/forumkit/releases/tag/v0.1.0

forumkit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to forumkit
+
+We welcome issues, discussions, and pull requests. This project is in alpha — your feedback shapes the direction.
+
+## Code of Conduct
+
+Be respectful, constructive, and assume good intent.
+
+## Reporting Issues
+
+- Use GitHub Issues for bugs, feature requests, documentation gaps
+- Include Python version, OS, relevant error trace
+- For security issues: email vinitpai@anthropic.com instead
+
+## Pull Requests
+
+1. Fork the repo
+2. Create a branch: `git checkout -b feature/my-feature`
+3. Write code following Google style guide (see [CLAUDE.md](CLAUDE.md))
+4. Add/update tests (pytest required)
+5. Run `ruff check --fix .` and `mypy . --strict`
+6. Commit with clear message (see below)
+7. Push and open PR with description of why (not just what)
+
+### Commit Message Format
+
+```
+<type>: <subject>
+
+<body (optional, explain why)>
+
+<footer (optional)>
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+Example:
+```
+feat: add timeout parameter to execute()
+
+Previously, execute() had no way to enforce time limits. This adds
+a configurable timeout_s parameter with exponential backoff on retry.
+
+Fixes #123
+```
+
+## Testing
+
+All new code requires tests:
+
+```bash
+# Run tests
+pytest tests/unit/ -v
+
+# Run with coverage
+pytest --cov=forumkit tests/unit/
+
+# Type check
+mypy forumkit/ --strict
+
+# Lint
+ruff check forumkit/
+```
+
+## Before Open Source
+
+This project is currently private beta. Before we open source (v1.0), we need:
+
+- [ ] Minimum 80% test coverage
+- [ ] Zero mypy strict errors
+- [ ] API documentation complete
+- [ ] 2-3 working examples
+- [ ] Security audit
+
+---
+
+Questions? Open a discussion or email the maintainer.

forumkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinit Pai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forumkit-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: forumkit
+Version: 0.1.0
+Summary: Multi-agent debate framework with structured consensus scoring and dissent tracking
+Project-URL: Homepage, https://github.com/vinitpai/forumkit
+Project-URL: Repository, https://github.com/vinitpai/forumkit
+Project-URL: Issues, https://github.com/vinitpai/forumkit/issues
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,consensus,debate,llm,multi-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: aioredis>=2.0
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: httpx>=0.27
+Requires-Dist: litellm>=1.40
+Requires-Dist: pydantic>=2.0
+Requires-Dist: structlog>=24.0
+Provides-Extra: all
+Requires-Dist: aioredis>=2.0; extra == 'all'
+Requires-Dist: asyncpg>=0.29; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: kafka-python>=2.0; extra == 'all'
+Requires-Dist: minio>=7.0; extra == 'all'
+Requires-Dist: neo4j>=5.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: coverage>=7.0; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: jepa
+Requires-Dist: minio>=7.0; extra == 'jepa'
+Requires-Dist: neo4j>=5.0; extra == 'jepa'
+Provides-Extra: kafka
+Requires-Dist: kafka-python>=2.0; extra == 'kafka'
+Provides-Extra: memory
+Requires-Dist: aioredis>=2.0; extra == 'memory'
+Requires-Dist: asyncpg>=0.29; extra == 'memory'
+Requires-Dist: httpx>=0.27; extra == 'memory'
+Description-Content-Type: text/markdown
+
+# forumkit
+
+The only Python multi-agent framework with a **structured debate protocol**: fan-out → challenge → rebuttal → consensus scoring.
+
+```python
+from forumkit import ForumModeratorBase, ResearcherBase, AgentConfig, AgentRole
+
+class MyAnalyst(ResearcherBase):
+    async def analyze(self, data):
+        # Independent analysis
+        return {"position": "...", "confidence": 0.8}
+
+    async def respond_to_challenge(self, challenge, context):
+        # Defend your position
+        return "Here's why I disagree..."
+
+class MyForum(ForumModeratorBase):
+    def _synthesize(self, analyses, consensus, data):
+        # Domain-specific consensus logic
+        if consensus.agreement_pct >= 66:
+            return "accepted", {"action": "approve"}
+        return "conditional", {"action": "review"}
+
+# Run a debate
+forum = MyForum(config, researchers=[analyst1, analyst2, analyst3])
+result = await forum.run_debate_round({"question": "Is X good?"})
+
+print(f"Consensus: {result.consensus.agreement_pct}% agree")
+print(f"Dissent: {result.consensus.strongest_dissent}")
+print(f"Anomaly?: {result.consensus.unanimous_anomaly}")  # Detects groupthink
+```
+
+## Why forumkit?
+
+**The problem:** CrewAI, PraisonAI, AutoGen, and others assume agents reach consensus by averaging opinions. In reality, minority views often reveal blind spots.
+
+**The solution:** forumkit enforces dissent:
+- Every agent analyzes independently
+- Agents actively challenge each other's positions
+- Minority opinions are surfaced, not discarded
+- Suspicious unanimity is flagged (`unanimous_anomaly` detection)
+- Outcomes are tied to consensus strength, not just majority vote
+
+**The result:** Better decisions with traceable dissent.
+
+## Quick Start
+
+### Install
+
+```bash
+pip install forumkit
+```
+
+### 5-minute example
+
+```python
+import asyncio
+from forumkit import ForumModeratorBase, ResearcherBase, AgentConfig, AgentRole, PersonaContext
+
+class Analyst(ResearcherBase):
+    async def analyze(self, data):
+        # Your LLM call here
+        return {
+            "persona_id": self.persona.persona_id,
+            "position": f"Analysis from {self.persona.name}",
+            "confidence": 0.75
+        }
+
+    async def respond_to_challenge(self, challenge, context):
+        return "I maintain my position because..."
+
+class DebateBoard(ForumModeratorBase):
+    def _synthesize(self, analyses, consensus, data):
+        synthesis = f"Consensus at {consensus.agreement_pct:.0f}%"
+        outcome = "approved" if consensus.agreement_pct >= 50 else "rejected"
+        return synthesis, outcome, None
+
+async def main():
+    config = AgentConfig(
+        agent_id="board-1", team_id=1, role=AgentRole.HEAD,
+        model_alias="gpt-4"
+    )
+
+    # Create 3 analysts with different personas
+    analysts = [
+        Analyst(AgentConfig(...), PersonaContext(
+            persona_id="p1", name="Optimist", system_prompt="..."
+        )),
+        # ... more analysts
+    ]
+
+    board = DebateBoard(config, analysts)
+    result = await board.run_debate_round({"question": "Approve proposal X?"})
+
+    print(f"Outcome: {result.outcome}")
+    print(f"Agreement: {result.consensus.agreement_pct}%")
+    print(f"Dissent: {result.consensus.dissent_count} voices disagree")
+    print(f"Anomaly: {result.consensus.unanimous_anomaly}")
+
+asyncio.run(main())
+```
+
+## Concepts
+
+### The Forum Protocol
+
+1. **Fan-out** — Every analyst independently evaluates the question
+2. **Challenge** — Analysts see each other's views and attack weak points
+3. **Rebuttal** — Each analyst responds to challenges
+4. **Score** — Consensus metrics computed: agreement %, confidence, dissent count
+5. **Synthesize** — Domain-specific outcome logic applied
+
+### Key Types
+
+- **BaseAgent** — Foundation for all agents. Role-gated: `HEAD` can delegate to children, `JUNIOR` cannot call LLM
+- **ResearcherBase** — Expert with persona, implements `analyze()` and `respond_to_challenge()`
+- **ForumModeratorBase** — Orchestrates the debate, computes consensus, applies domain logic
+- **ConsensusScore** — Result includes `agreement_pct`, `dissent_count`, **`unanimous_anomaly`** (detects suspicious unanimity)
+
+## Memory Backends
+
+forumkit supports three memory types:
+
+| Backend | Use | Backend |
+|---------|-----|---------|
+| **Working** | In-session cache | Redis (TTL) |
+| **Episodic** | Long-term experience | PostgreSQL |
+| **Semantic** | Vector embeddings | Qdrant |
+
+All are optional. Use the facade:
+
+```python
+from forumkit.memory import MemoryManager
+
+memory = MemoryManager(
+    redis_url="redis://localhost:6379",
+    pg_url="postgresql://localhost/mydb",
+    qdrant_url="http://localhost:6333"
+)
+
+await memory.initialize()
+# Use: memory.working.set(), memory.episodic.store(), memory.semantic.search()
+```
+
+## Docs
+
+- **[API Reference](docs/API.md)** — All public types and methods
+- **[Concepts](docs/CONCEPTS.md)** — Architecture deep-dive
+- **[Examples](docs/examples/)** — Working code samples
+
+## Testing
+
+```bash
+pytest tests/unit/ -v
+pytest tests/integration/ -v  # Requires Docker (Redis, PostgreSQL)
+```
+
+## Security
+
+forumkit includes prompt injection defense:
+
+```python
+from forumkit.security import sanitize_for_prompt
+
+clean = sanitize_for_prompt(user_input)
+# Applies: NFKC normalize, strip BiDi/control chars, remove injection patterns
+```
+
+## Status
+
+**v0.1.0 — Alpha**. API is stable; docs are being refined. Not yet open source (private beta).
+
+## License
+
+MIT
+
+## Contact
+
+Issues: GitHub Issues
+Questions: vinitpai@anthropic.com

forumkit-0.1.0/README.md

@@ -0,0 +1,180 @@
+# forumkit
+
+The only Python multi-agent framework with a **structured debate protocol**: fan-out → challenge → rebuttal → consensus scoring.
+
+```python
+from forumkit import ForumModeratorBase, ResearcherBase, AgentConfig, AgentRole
+
+class MyAnalyst(ResearcherBase):
+    async def analyze(self, data):
+        # Independent analysis
+        return {"position": "...", "confidence": 0.8}
+
+    async def respond_to_challenge(self, challenge, context):
+        # Defend your position
+        return "Here's why I disagree..."
+
+class MyForum(ForumModeratorBase):
+    def _synthesize(self, analyses, consensus, data):
+        # Domain-specific consensus logic
+        if consensus.agreement_pct >= 66:
+            return "accepted", {"action": "approve"}
+        return "conditional", {"action": "review"}
+
+# Run a debate
+forum = MyForum(config, researchers=[analyst1, analyst2, analyst3])
+result = await forum.run_debate_round({"question": "Is X good?"})
+
+print(f"Consensus: {result.consensus.agreement_pct}% agree")
+print(f"Dissent: {result.consensus.strongest_dissent}")
+print(f"Anomaly?: {result.consensus.unanimous_anomaly}")  # Detects groupthink
+```
+
+## Why forumkit?
+
+**The problem:** CrewAI, PraisonAI, AutoGen, and others assume agents reach consensus by averaging opinions. In reality, minority views often reveal blind spots.
+
+**The solution:** forumkit enforces dissent:
+- Every agent analyzes independently
+- Agents actively challenge each other's positions
+- Minority opinions are surfaced, not discarded
+- Suspicious unanimity is flagged (`unanimous_anomaly` detection)
+- Outcomes are tied to consensus strength, not just majority vote
+
+**The result:** Better decisions with traceable dissent.
+
+## Quick Start
+
+### Install
+
+```bash
+pip install forumkit
+```
+
+### 5-minute example
+
+```python
+import asyncio
+from forumkit import ForumModeratorBase, ResearcherBase, AgentConfig, AgentRole, PersonaContext
+
+class Analyst(ResearcherBase):
+    async def analyze(self, data):
+        # Your LLM call here
+        return {
+            "persona_id": self.persona.persona_id,
+            "position": f"Analysis from {self.persona.name}",
+            "confidence": 0.75
+        }
+
+    async def respond_to_challenge(self, challenge, context):
+        return "I maintain my position because..."
+
+class DebateBoard(ForumModeratorBase):
+    def _synthesize(self, analyses, consensus, data):
+        synthesis = f"Consensus at {consensus.agreement_pct:.0f}%"
+        outcome = "approved" if consensus.agreement_pct >= 50 else "rejected"
+        return synthesis, outcome, None
+
+async def main():
+    config = AgentConfig(
+        agent_id="board-1", team_id=1, role=AgentRole.HEAD,
+        model_alias="gpt-4"
+    )
+
+    # Create 3 analysts with different personas
+    analysts = [
+        Analyst(AgentConfig(...), PersonaContext(
+            persona_id="p1", name="Optimist", system_prompt="..."
+        )),
+        # ... more analysts
+    ]
+
+    board = DebateBoard(config, analysts)
+    result = await board.run_debate_round({"question": "Approve proposal X?"})
+
+    print(f"Outcome: {result.outcome}")
+    print(f"Agreement: {result.consensus.agreement_pct}%")
+    print(f"Dissent: {result.consensus.dissent_count} voices disagree")
+    print(f"Anomaly: {result.consensus.unanimous_anomaly}")
+
+asyncio.run(main())
+```
+
+## Concepts
+
+### The Forum Protocol
+
+1. **Fan-out** — Every analyst independently evaluates the question
+2. **Challenge** — Analysts see each other's views and attack weak points
+3. **Rebuttal** — Each analyst responds to challenges
+4. **Score** — Consensus metrics computed: agreement %, confidence, dissent count
+5. **Synthesize** — Domain-specific outcome logic applied
+
+### Key Types
+
+- **BaseAgent** — Foundation for all agents. Role-gated: `HEAD` can delegate to children, `JUNIOR` cannot call LLM
+- **ResearcherBase** — Expert with persona, implements `analyze()` and `respond_to_challenge()`
+- **ForumModeratorBase** — Orchestrates the debate, computes consensus, applies domain logic
+- **ConsensusScore** — Result includes `agreement_pct`, `dissent_count`, **`unanimous_anomaly`** (detects suspicious unanimity)
+
+## Memory Backends
+
+forumkit supports three memory types:
+
+| Backend | Use | Backend |
+|---------|-----|---------|
+| **Working** | In-session cache | Redis (TTL) |
+| **Episodic** | Long-term experience | PostgreSQL |
+| **Semantic** | Vector embeddings | Qdrant |
+
+All are optional. Use the facade:
+
+```python
+from forumkit.memory import MemoryManager
+
+memory = MemoryManager(
+    redis_url="redis://localhost:6379",
+    pg_url="postgresql://localhost/mydb",
+    qdrant_url="http://localhost:6333"
+)
+
+await memory.initialize()
+# Use: memory.working.set(), memory.episodic.store(), memory.semantic.search()
+```
+
+## Docs
+
+- **[API Reference](docs/API.md)** — All public types and methods
+- **[Concepts](docs/CONCEPTS.md)** — Architecture deep-dive
+- **[Examples](docs/examples/)** — Working code samples
+
+## Testing
+
+```bash
+pytest tests/unit/ -v
+pytest tests/integration/ -v  # Requires Docker (Redis, PostgreSQL)
+```
+
+## Security
+
+forumkit includes prompt injection defense:
+
+```python
+from forumkit.security import sanitize_for_prompt
+
+clean = sanitize_for_prompt(user_input)
+# Applies: NFKC normalize, strip BiDi/control chars, remove injection patterns
+```
+
+## Status
+
+**v0.1.0 — Alpha**. API is stable; docs are being refined. Not yet open source (private beta).
+
+## License
+
+MIT
+
+## Contact
+
+Issues: GitHub Issues
+Questions: vinitpai@anthropic.com