Octochains is a lightweight, zero-dependency Python framework for Collaborative AI Reasoning. It moves away from "monolithic" AI responses toward a parallel, multi-expert architecture that eliminates "Expert Blindspots" in high-stakes decision-making.
By broadcasting a single complex problem to a pool of isolated specialists, Octochains ensures that every angle, from clinical diagnostics to legal compliance, is evaluated independently before reaching a final consensus.
Even State-of-the-Art models can fall into "Reasoning Traps", a form of cognitive tunnel vision where a model commits to a logical path too early. Octochains eliminates this through a MapReduce-inspired architecture designed for multidisciplinary precision and high-stakes transparency:
- Broadcasting: The full, complex problem is passed directly to every specialized agent in the pool, ensuring no context is lost or filtered by a "master" model.
- Parallel Execution: Agents operate simultaneously in isolated, threaded environments. This ensures that specialist findings remain unbiased by the opinions of other agents during the initial reasoning phase.
- Traceability & Compliance: To meet EU AI Act requirements for monitorable AI, Octochains generates comprehensive trace logs for every decision. Every internal thought process, specialist conflict, and evidence-based rationale is logged and downloadable for human audit.
- The Aggregator: A final "Chief Justice" agent synthesizes these conflicting or supporting insights into a single transparent, explainable, and robust outcome.
Octochains is designed to be developer-first and model-agnostic.
pip install octochainsfrom octochains import Agent, tool
class Specialist(Agent):
def __init__(self):
super().__init__(
role="Legal Expert",
goal="Identify liability risks"
)
@tool
def check_compliance(self, text: str):
"""Analyzes text for regulatory non-compliance."""
# Framework automatically generates JSON schema for this tool
return "Compliant"
def execute(self, data: str) -> str:
# Use any LLM here (OpenAI, Gemini, Ollama, etc.)
# The 'data' passed here is the full complex problem.
return f"Legal Analysis: {data}"from octochains import Aggregator
class ChiefConsensusOfficer(Aggregator):
def __init__(self):
super().__init__(
role="Chief Aggregator",
goal="Synthesize expert opinions into a final verdict"
)
def synthesize(self, problem_data: str, agent_reports: dict[str, str]) -> str:
"""
Receives the original problem and a dictionary of reports.
Key: Agent Role, Value: Agent output string.
"""
# Here you can call a high-reasoning LLM to compare the reports
# or implement custom logic to resolve conflicts.
verdict = "APPROVED"
for role, report in agent_reports.items():
if "RISK" in report.upper():
verdict = "REJECTED"
return f"Final Decision: {verdict} based on {len(agent_reports)} expert inputs."from octochains import Engine
# Initialize your experts and the aggregator
engine = Engine(
agents=[legal_expert, finance_expert, tech_expert],
aggregator=ChiefConsensusOfficer()
)
# Broadcast the complex problem to all agents at once
report = engine.run("Full Project Alpha Investment Case File...")
print(f"Consensus: {report.consensus}")
print(f"Audit Trail: {report.traces}")
While Octochains is a universal framework, its power is best demonstrated in multidisciplinary medicine. The featured example simulates a clinical team to rule out underlying heart conditions, psychological factors, or respiratory issues that might be missed by a single-model analysis.
- Cardiologist Agent: Focuses on arrhythmias and structural abnormalities.
- Psychologist Agent: Identifies conditions like anxiety or panic disorders.
- Pulmonologist Agent: Assesses respiratory causes such as asthma or COPD.
The Agent & Aggregator Hub Octochains is built to be modular. We are developing an Agent & Aggregator Hub where the community can contribute, publish, and reuse specialized reasoning modules.
src/octochains/
├── __init__.py <-- Core framework exports
├── base.py <-- Abstract Base Classes (Agent/Aggregator)
├── engine.py <-- Parallel Broadcast Engine
├── schema.py
├── exceptions.py <-- Error handling
│
├── agents/ <-- THE AGENT HUB
│ ├── medical/
│ │ ├── __init__.py <-- Export: Cardiologist, Neurologist, etc.
│ │ ├── cardiology.py
│ │ └── neurology.py
│ ├── legal/
│ │ ├── __init__.py <-- Export: Compliance, ContractExpert
│ │ └── compliance.py
│ └── finance/
│ ├── __init__.py
│ └── analyst.py
│
└── aggregators/ <-- THE AGGREGATOR LIBRARY
├── medical/
│ ├── __init__.py <-- Export: ChiefMedicalOfficer
│ └── cmo.py
└── logic/ <-- Standard decision-making logic
├── __init__.py <-- Export: MajorityVote, WeightedConsensus
├── majority.py
└── consensus.py
Demo Examples Every demo in Octochains is designed as a standalone, reproducible case study. This ensures the core framework remains lightweight while allowing specific use cases to have their own environment.
demo-examples/
└── 01-ai-agents-for-medical-diagnostics/
├── medical_reports/ <-- Sample patient dossiers
├── results/ <-- Historical audit logs of agent outputs
├── requirements.txt <-- Isolated dependencies (e.g., biopython)
└── run_demo.py <-- Entry point for the diagnostic engine
We are expanding Octochains from a library into a comprehensive ecosystem for high-stakes AI reasoning.
- The Agent Hub: A community-driven marketplace for pre-tuned specialist modules. Developers can build and publish their own "experts" (e.g., M&A Due Diligence, Cybersecurity Threat Hunter, or Endocrinology Specialist) for others to snap into their own chains.
Octochains is open-source under the MIT license. For enterprise features and custom integrations contact: ahmad.vh7@gmail.com