octochains

Octochains is a lightweight Python framework for parallel, isolated multi-agent reasoning and consensus. It is built for complex, decomposable tasks that require independent, multi-perspective analysis without logical contamination.

Unlike traditional sequential agent chains—in which models influence each other through a shared chat history—Octochains executes domain experts in parallel isolated threads. Every angle of a high-stakes decision, from clinical diagnosis to financial risk and legal audit, is evaluated in a pristine isolated environment before being synthesized by a centralized validation layer.

Why Octochains? Standard multi-agent frameworks suffer from cognitive tunneling and groupthink, where early outputs determine downstream reasoning. Octochains eliminates this through a robust thread-safe architecture:

• Parallel isolation: Expert agents run in private threads with zero awareness of peer outputs, guaranteeing objective, uncontaminated analysis.
• Centralized consensus: A dedicated aggregator audits the isolated reports, resolves logical conflicts and highlights evidence gaps before issuing a type-safe verdict.
• Audit-first design: Every execution generates an immutable, 100% traceable log of expert rationale and error states, meeting the EU AI Act's requirements for monitorable enterprise AI.
• Portable skills: Agents can be equipped with skills, i.e. markdown-based knowledge packages with zero external dependencies when parsed, letting you inject domain processes without writing any prompt engineering code.

Octochains is built on architectural principles validated in the Google Research / MIT study "Towards a Science of Scaling Agent Systems." The research confirms that for analytical, decomposable tasks, parallel isolated architectures deliver a massive performance difference compared with standard sequential models.

Octochains is designed with a developer-first, model-agnostic and lightweight philosophy.

1. Bring your own LLM Octochains is a "pure engine." It does not force you to install heavy SDKs or learn proprietary API wrappers. You retain 100% control over your own models and API keys.

2. 60-second demo Three domain experts analyze a case in parallel, fully isolated from one another, then a synthesizer merges their reports into a single executive verdict. This is a complete parallel isolated reasoning pipeline, with no custom classes and no prompt engineering. See the official preset agent catalog to learn about all 13 available experts.

3. Define expert agents from scratch Agents inherit from Agent and implement the execute() method. The framework builds a strict "enforced perspective" identity prompt for you, while you retain full control over the execution loop. Using tools? You own the execute() loop! You can bypass simple text wrappers and inject the provider's native tool schemas (such as OpenAI functions or external database hooks) directly into the API call.

4. Define the aggregator The aggregator waits for all experts to finish, reads their parallel reports, and synthesizes the final execution decision.

5. Run the parallel engine The engine starts all agents concurrently, captures individual thread failures without crashing the pool, and pipes clean data to the aggregator.

Official preset agents In addition to custom Agent subclasses, Octochains ships with prebuilt experts, each a SkilledAgent bundled with curated, versioned skills. Import them directly from octochains.agents.presets.

• Launch the due diligence committee: for evaluating a business, product, or investment case in parallel from each executive's perspective.
• Regulatory and compliance auditor: for flagging legal and regulatory risks before they reach a human reviewer.
• Security auditor: for analyzing security logs and access events from complementary, non-overlapping perspectives, with each preset scoped to its own layer so findings do not overlap or contradict one another. Each preset accepts extra_skills=[...] to layer your own domain knowledge on top of the official skills without subclassing.

Writing custom skills A skill is a markdown file with a simple key: value frontmatter block, no YAML library required, no nested lists or objects, just flat fields. Load it into any agent. Skills attached to an agent are shown by default in every prompt by name and description (cheap, always on). The full skill content is loaded only on demand; see Agent.get_skill() and Agent.load_relevant_skills() in base.py for manual and automatic selection.

Official enterprise aggregators While Octochains lets you build custom aggregators, we provide out-of-the-box modules designed for enterprise-grade verification and consensus.

1. ConflictChecker The deterministic "chief justice" in your architecture. It audits expert reports for logical contradictions, timeline mismatches, and incompatible claims.

• Strategy 1 (prompt matrix): uses structuredConduct single-call audits of the internal pairwise comparison matrix.
• Strategy 2 (parallel pairwise): multithreaded execution, programmatically generating isolated bilateral threads across all unique agent pairs, enabling absolute, reproducible auditing capability.
• Mathematical safety gate: if an upstream failure leaves fewer than 2 surviving reports, the audit is automatically aborted without wasting API tokens.

1. Synthesizer "Chief Integration Officer." It merges multiple isolated expert reports into a single coherent executive narrative, automatically resolving redundancy, strictly mapping citations to the responding agents, and zeroing confidence scores when the upstream pipeline fails.
2. WeightedSynthesizer A Synthesizer variant for proportional emphasis. When certain perspectives should shape the final narrative more than others as a baseline—not just when they conflict—you assign a weight to each agent role; higher-weight perspectives drive the framing and conclusions, while lower-weight perspectives are blended in as supporting context. This differs from ConflictChecker: it is about prominence in the mix, and applies even when all experts fully agree.

• Missing weights: any responding role not present in the weights falls back to equal standing (default_weight=1.0); unweighted agents are never silently dropped.
• Normalization: weights are normalized to sum to 1.0; weights_applied and dominant_perspective are recorded on the result as a deterministic audit trail of how the mixture was formed.
• Degenerate case: equal weights produce output equivalent to the plain Synthesizer. See the /cookbook/ directory for complete examples of these aggregators.

Repository structure

• /src/octochains/engine.py: high-performance parallel orchestrator with thread-level exception capture.
• /src/octochains/base.py: high-level abstract base class with automatic threshold gates and anti-hallucination prompt injection.
• /src/octochains/skills.py: the Skill class, which parses SKILL.md frontmatter + content with zero external dependencies.
• /src/octochains/agents/presets.py: official ready-to-use domain experts (CFO, CTO, GDPR auditor, etc.).
• /src/octochains/agents/skilled_agent.py: SkilledAgent,the concrete, ready-to-use Agent that powers all official presets.
• /src/octochains/agents/skills/: bundled SKILL.md knowledge packs that power the official presets.
• /src/octochains/aggregators/: standardized synthesis and deterministic auditing logic.

We are actively expanding Octochains from a library into a comprehensive ecosystem for high-stakes reasoning:

• Expanding the preset catalog: community-contributed skills are reviewed and merged into the official preset library.
• Expanding the aggregator suite: out-of-the-box integration of democratic majority-voting flows, strict Minimax boundary-testing gates, and taxonomic classifiers.
• Octonodes: a production-grade visual application interface that lets architects drag and drop parallel topologies, map data hooks, and export automated Python/Rust deployment code.
• HITL Gateway: a native human-in-the-loop interception protocol that lets domain experts step in at critical decision forks or review aggregated conflict logs before execution.

Octochains is Fair-Code, distributed under the Business Source License 1.1.

• Personal and internal use: free to use, modify, and extend for personal projects, academic research, and internal company workflows.
• Commercial providers: without an enterprise license, you may not offer Octochains as hosted SaaS reasoning infrastructure, or sell a commercial wrapper around the core engine.
• Open-source guarantee: to protect the codebase as a permanent public good, this release includes a deterministic sunset clause: on May 10, 2030, the license automatically converts to Apache 2.0 (open source).

To access enterprise reasoning features or a commercial license, contact: ahmad.vh7@gmail.com

Octochains is currently in Beta. We are iterating on the orchestration engine API. Before v1.0.0, breaking changes may occur in minor versions.