Octochains
A lightweight Python framework where expert agents reason in fully isolated parallel threads and a centralized consensus layer synthesizes the verdict, eliminating cross-contamination and groupthink of sequential agent chains.
- Source repo
- ahmadvh/octochains
- Stars
- ★ 377
- Last updated
- 3d ago
- License
- NOASSERTION
- Primary language
- Python
- FA score
- 69/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- M&A due-diligence teams that need independent CFO, CTO, and CRO perspectives on an acquisition target before committing, without any perspective contaminating another
- Not a fit if
- Teams needing sequential conversational automation; README says use a single agent
- Companies planning to offer Octochains as managed SaaS reasoning infrastructure
- Production teams that cannot accept breaking API changes before v1.0.0
- Source review
- 69/100 · Some gaps
What does this agent do, and when should you use it?
Octochains (PyPI package octochains, version 0.7.0) is a Python multi-agent reasoning framework built for high-stakes, decomposable tasks. Its core execution model is parallel isolated threads: each domain specialist agent runs in a private thread with zero awareness of peer outputs, eliminating the cognitive bias and groupthink found in traditional sequential frameworks. The isolated reports are then processed by centralized aggregators (Synthesizer, ConflictChecker, WeightedSynthesizer) that audit conflicts and produce a type-safe, auditable verdict. The framework follows an audit-first design: every execution generates an immutable, 100% traceable log of expert rationale and error states, aligning with EU AI Act requirements for monitorable enterprise AI. Dependencies are minimal: only Pydantic, with the Skills (markdown knowledge packs) parsed entirely with the standard library. Octochains is a model-agnostic "pure engine" — you bring your own LLM callable and are never forced into a vendor SDK.
Octochains' Engine (src/octochains/engine.py) launches all specialist agents (subclasses of the Agent base class implementing execute()) concurrently, traps thread-level exceptions without crashing the pool, and pipes structured reports to an Aggregator. Out-of-the-box components include: 13 preset specialists (cfo_agent, cto_agent, cro_agent, cpo_agent, cmo_agent, plus data_sovereignty_auditor, ai_risk_assessor, phi_sanitizer, licensing_reviewer, security_threat_hunter, insider_threat_analyst, identity_access_auditor, and breach_notification_analyst in octochains.agents.presets); three official aggregators (ConflictChecker with prompt-matrix auditing, O(N²) parallel pairwise audits, and a mathematical safety gate; Synthesizer for cohesive executive narratives; WeightedSynthesizer for per-role weighted emphasis); and a markdown-frontmatter Skill system (loaded via Skill.from_file, consumed by SkilledAgent, extensible via extra_skills). You plug in any LLM through a my_llm(prompt) callable and call engine.run(problem_data=...) to receive a report containing consensus and traces for auditing.
- M&A due-diligence teams that need independent CFO, CTO, and CRO perspectives on an acquisition target before committing, without any perspective contaminating another
- Compliance teams running GDPR data-sovereignty audits, EU AI Act risk tiering, and PHI compliance checks in parallel before product launch
- Security teams analyzing security logs from four complementary, non-overlapping angles: external intrusion (MITRE ATT&CK), insider threats, identity/access, and breach notification
- Open-source compliance engineers assessing copyleft (GPL/AGPL) contamination risk in dependency trees
- Enterprises needing complete, immutable AI decision-reasoning logs to satisfy EU AI Act monitoring requirements
How do you install or deploy this agent?
Install with pip: pip install octochains. Requires a Python environment; the only third-party dependency is Pydantic (Skills parsing is pure stdlib). You must supply your own LLM API credentials (e.g., an OpenAI API key) since no model SDK is bundled.
How do you use this agent?
Step 1 — define an LLM callable: write def my_llm(prompt: str) -> str using any client (e.g., openai.Client). Step 2 — assemble the engine: from octochains.agents.presets import cfo_agent, cro_agent, data_sovereignty_auditor; from octochains.aggregators import Synthesizer; from octochains.engine import Engine; engine = Engine(agents=[cfo_agent(my_llm), cro_agent(my_llm), data_sovereignty_auditor(my_llm)], aggregator=Synthesizer(llm_callable=my_llm)). Step 3 — run: report = engine.run(problem_data="...", show_log=True), then read report.consensus.narrative and report.traces. Custom agents inherit from octochains.base.Agent and implement execute(); custom aggregators inherit from octochains.base.Aggregator. The /cookbook/ directory contains full aggregator examples.
What are this agent's strengths and limitations?
- Parallel isolated execution architecturally eliminates the cognitive bias caused by sequential frameworks where agents read each other's chat logs — backed by research on parallel-isolated architectures (Google Research/MIT study reports +80.8% gain on the Finance-Agent benchmark)
- Extremely lightweight: only one third-party dependency (Pydantic); Skills parse with pure stdlib, no heavy LangChain-style dependency chain
- Model-agnostic pure-engine design: you fully control the LLM client, API keys, and tool injection (native tool schemas can be wired into execute())
- Audit-first: immutable, 100% traceable execution logs with error states, aligned with EU AI Act enterprise compliance needs
- Thread-level fault tolerance: individual agent failures are trapped without crashing the pool; ConflictChecker's mathematical safety gate aborts audits without wasting API tokens on upstream failures
- Licensed under BUSL 1.1 (fair-code): you cannot offer it as managed SaaS reasoning infrastructure or sell a commercial wrapper without an enterprise license; although it auto-transitions to Apache 2.0 on May 10, 2030, you must verify your business model complies before adopting
- Currently in Beta (v0.7.0); the orchestration engine API may introduce breaking changes in minor releases until v1.0.0
- GitHub license metadata reads NOASSERTION, so automated compliance scanners may not recognize it — legal review requires manually checking the LICENSE file
- Not a conversational automation framework: for sequential tasks (the PlanCraft scenario in the research), the README explicitly recommends a single agent instead — the fit is narrower than general agent frameworks
- Pairwise auditing (pairwise_audit=True) is O(N²), so API costs grow significantly with more agents
How does this agent compare with similar options?
The README provides its own comparison: versus sequential frameworks (CrewAI, AutoGen, based on turn-based chat), Octochains offers parallel isolated threads and zero-peer-awareness bias protection; versus routing-graph frameworks (LangGraph, DAG-based), Octochains focuses on high-stakes consensus and auditing with lighter dependencies. Sequential frameworks fit conversational task automation; LangGraph fits complex stateful workflows.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Octochains This agent | 69 · Some gaps | Library / SDKFree + model costs | ★ 377 | 3d ago | Python | OpenAI API |
| Marvin – A Python Framework for AI Workflows | 45 · Major gaps | Library / SDKFree + model costs | ★ 6.2k | 1mo ago | Python | OpenAI API |
| Langroid | 70 · Some gaps | Library / SDKFree + model costs | ★ 4.1k | today | Python | Claude Code · OpenAI API |
| Selectools | 65 · Some gaps | Library / SDKFree + model costs | ★ 11 | 9d ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
BYO-LLM design keeps API keys in user-owned code; single dependency (pydantic); the engine itself is a pure orchestrator with no built-in external side effects — external actions only occur via user-written execute(), which is a sound least-privilege posture. Deductions: no HITL/user-confirmation mechanism (roadmap only); sensitive-data handling relies solely on preset prompt personas (e.g., phi_sanitizer) with no actual log redaction or PII-leak safeguards; traces/audit logs may carry full problem data sent to LLMs with no stated scrubbing policy; no rollback mechanism; the scarf.sh tracking pixel in README is an undisclosed outbound data beacon.
Tests demonstrate strong self-consistency: deterministic trace ordering, require_all_agents gate halting before the aggregator, prompt timeout return, distinct NoValidReportsError vs AggregatorError, constructor-time duplicate-role validation. Failure messages are specific and individually asserted (3). Deduction: dependency availability rests on a single unpinned-upper-bound pydantic requirement (2); the real LLM call path is not validated in-source.
Audience and scenarios are clearly framed (high-stakes analysis, due diligence, compliance audits); model-agnostic callables and Pydantic output_format support broad fit (3). Deductions: capability boundaries are touched only coarsely (PlanCraft row); tool-injection precision is delegated entirely to user execute() code with no framework guardrails; environment claims are generic ('OS independent') with no threading caveats for platforms.
Excellent information architecture: README maps repository structure to code paths and the full 13-preset catalog (3). License handling is thorough: full BUSL 1.1 text, the 2030-05-10 Apache 2.0 sunset clause, and SaaS restrictions are explicit (3). Known limitations partially disclosed (Beta, breaking changes) (2). Deductions: no CHANGELOG file; version exists only as a badge; maintenance is a single personal email with no governance or response commitment; no FAQ; post-install setup depends on Quickstart snippets only.
Parallel-isolation-plus-aggregation is a genuine differentiator vs sequential frameworks, and the one-dependency design keeps integration cost low (3). Deductions: output usability still depends on user-side formatting; ConflictChecker output is text-shaped rather than structured for downstream gating; the +80.8% / +57.2% gains are borrowed from external research, not measured in this repo, so marginal value is only partially substantiated.
Architectural claims are cross-checkable against source paths and tests; the performance claim links to a specific external study (2). Deductions: benchmark numbers have no in-repo reproduction material and remain external assertions lacking corroboration; facts and inference are mostly separated, but absolutist marketing phrasing ('100% cognitive bias protection', '100% traceable') is unqualified.
- The README embeds a scarf.sh tracking pixel that fires a third-party request on render — beware in privacy-sensitive environments.
- License is BUSL 1.1 (not OSI open source): managed-service commercial use is prohibited and Apache 2.0 conversion only occurs in 2030; get legal review before commercial integration.
- Sensitive-data (PHI/PII) protection is prompt-persona only; the framework ships no actual log redaction or exfiltration safeguards — harden externally for regulated data.
- No HITL confirmation or rollback exists; high-stakes deployments must add human-review gates externally.
- No CHANGELOG and Beta status mean breaking changes in minor releases; pin versions for production.
- Performance-gain figures are cited from external research and are not validated within this repository; do not treat them as procurement evidence.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * cookbook: add AI Feature Compliance Gate demo using Anthropic by @OrienSpec in https://github.com/ahmadvh/octochains/pull/24 * Added Security agent preset- insider threat analyst by @Leenaa-patil in https://github.com/ahmadvh/octochains/pull/25 * feat: add WeightedSynthesizer aggregator by @OrienSpec in https://github.com/ahmadvh/octochains/pull/23 * feat(presets): add breach_notification_analyst security preset (#20) by @shariqueahmad108-ship-it in https://github.com/ahmadvh/octochains/pull/26 New Contributors …View on GitHub ↗ -
Release notes excerpt
Added Security Threat Hunter Preset Added security_threat_hunter, a new official preset for identifying intrusion patterns and anomalous network behavior. Contributed by [@Leenaa-patil](https://github.com/Leenaa-patil) — our first community-contributed preset! 🎉 Engine Resilience Controls …View on GitHub ↗ -
Release notes excerpt
Full Changelog: https://github.com/ahmadvh/octochains/compare/v0.4.1...v0.5.0 [0.5.0] - 2026-07-15 Added Zero-Dependency Skills Engine Introduced the Skill and SkilledAgent classes to parse domain expertise and operational procedure directly from structured Markdown (SKILL.md) files. Features a native frontmatter parser for metadata (name, description, version) that operates entirely on the Python standard library, requiring no external YAML dependencies. Regulatory & Compliance Auditors …View on GitHub ↗