confab-framework 0.3.0__tar.gz

confab_framework-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dennis Chou
+
+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.

confab_framework-0.3.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: confab-framework
+Version: 0.3.0
+Summary: Structural confabulation detection and prevention for multi-agent systems
+License-Expression: MIT
+Project-URL: Repository, https://github.com/dennischoubot-glitch/confab-framework
+Project-URL: Issues, https://github.com/dennischoubot-glitch/confab-framework/issues
+Keywords: agents,confabulation,verification,multi-agent,llm,ai-safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# confab-framework
+
+Structural confabulation detection and prevention for multi-agent systems.
+
+Agents state falsehoods confidently. Other agents copy them forward indefinitely. This framework makes verification structural (enforced by code) rather than aspirational (suggested by docs).
+
+## Install
+
+```bash
+pip install confab-framework
+```
+
+Or from source:
+
+```bash
+pip install -e ./core/confab
+```
+
+## Quick Start
+
+```bash
+pip install confab-framework
+cd your-project/
+confab init                        # generate a confab.toml
+# Edit confab.toml — add your priority/handoff files to files_to_scan
+confab gate                        # verify carry-forward claims against reality
+```
+
+### Python API
+
+```python
+from confab import ConfabGate
+
+# From a config file
+gate = ConfabGate("confab.toml")
+report = gate.run()
+
+if report.has_failures:
+    print(report.format_report())
+elif report.has_stale:
+    print(f"{report.stale_claims} stale claims need verification")
+else:
+    print(f"Clean: {report.passed} claims verified")
+
+# Check inline text directly
+outcomes = gate.check("Audio pipeline blocked on OPENAI_API_KEY")
+for o in outcomes:
+    print(f"{o.result.value}: {o.evidence}")
+```
+
+## How It Works
+
+Agents in multi-agent systems pass claims forward at handoff points — "the pipeline is blocked on X," "file Y exists," "the config is ready." When an agent states a falsehood confidently, the next agent copies it forward. The confab framework breaks this cascade by extracting claims from handoff text, auto-verifying them against reality (filesystem, environment variables, script syntax, config parsing, pipeline outputs), and tracking how long unverified claims persist. Claims that fail verification get flagged; claims that linger without verification get marked stale. The gate runs at every agent handoff point, supplying the oracle bits that distinguish confabulation from understanding.
+
+The pipeline: **Extract** (scan for claims) → **Classify** (type + verifiability) → **Verify** (check against ground truth) → **Track** (SQLite persistence across runs) → **Report** (failures + staleness + tree health).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `confab gate` | Run the full cascade gate |
+| `confab check "text"` | Check inline text for claims |
+| `confab extract file.md` | Extract claims without verifying |
+| `confab quick` | One-line gate summary |
+| `confab prune` | Identify stale build sections to remove |
+| `confab sweep` | Show tracked claims by staleness |
+| `confab sweep --stats` | Tracker statistics |
+| `confab report` | System health dashboard (gate + supports + coverage) |
+| `confab init` | Generate a starter `confab.toml` |
+
+## Configuration
+
+`confab.toml` in your workspace root:
+
+```toml
+[confab]
+files_to_scan = ["docs/priorities.md", "notes/handoff.md"]
+stale_threshold = 3
+db_path = "confab_tracker.db"
+
+[confab.env_vars]
+known = ["OPENAI_API_KEY", "DATABASE_URL"]
+
+[confab.pipelines]
+"my_pipeline.py" = ["output/data/", "output/report.json"]
+
+# Optional: name-based pipeline matching for status claims
+[confab.pipeline_names]
+"data pipeline" = "my_pipeline.py"
+
+# Optional: count verification sources
+[confab.count_sources.my_entries]
+file = "data/entries.json"
+type = "json_array"
+json_path = "entries"
+
+[confab.count_sources.task_queue]
+file = "queue.md"
+type = "regex_count"
+pattern = "^###\\s+Task\\s+\\d+"
+rate_per_day = 3.0
+```
+
+Without a config file, the framework auto-detects context and uses sensible defaults.
+
+## Claim Types
+
+| Type | Example | Verification |
+|------|---------|-------------|
+| `file_exists` | "config.json is ready" | `os.path.exists()` |
+| `file_missing` | "output.csv doesn't exist" | `os.path.exists()` |
+| `env_var` | "blocked on OPENAI_API_KEY" | `.env` files + `os.environ` |
+| `pipeline_works` | "audio pipeline operational" | Output artifact check |
+| `pipeline_blocked` | "publishing blocked" | Output artifact check |
+| `script_runs` | "generate.py works" | `py_compile` + import check |
+| `config_present` | "settings.toml configured" | Parse + key check |
+| `count_claim` | "144 tests passing" | Source-specific count |
+
+## Architecture
+
+See [DESIGN.md](DESIGN.md) for the full architecture, including the cascade propagation problem, verification methods, and the gate's role at agent handoff points.
+
+## License
+
+MIT

confab_framework-0.3.0/README.md

@@ -0,0 +1,125 @@
+# confab-framework
+
+Structural confabulation detection and prevention for multi-agent systems.
+
+Agents state falsehoods confidently. Other agents copy them forward indefinitely. This framework makes verification structural (enforced by code) rather than aspirational (suggested by docs).
+
+## Install
+
+```bash
+pip install confab-framework
+```
+
+Or from source:
+
+```bash
+pip install -e ./core/confab
+```
+
+## Quick Start
+
+```bash
+pip install confab-framework
+cd your-project/
+confab init                        # generate a confab.toml
+# Edit confab.toml — add your priority/handoff files to files_to_scan
+confab gate                        # verify carry-forward claims against reality
+```
+
+### Python API
+
+```python
+from confab import ConfabGate
+
+# From a config file
+gate = ConfabGate("confab.toml")
+report = gate.run()
+
+if report.has_failures:
+    print(report.format_report())
+elif report.has_stale:
+    print(f"{report.stale_claims} stale claims need verification")
+else:
+    print(f"Clean: {report.passed} claims verified")
+
+# Check inline text directly
+outcomes = gate.check("Audio pipeline blocked on OPENAI_API_KEY")
+for o in outcomes:
+    print(f"{o.result.value}: {o.evidence}")
+```
+
+## How It Works
+
+Agents in multi-agent systems pass claims forward at handoff points — "the pipeline is blocked on X," "file Y exists," "the config is ready." When an agent states a falsehood confidently, the next agent copies it forward. The confab framework breaks this cascade by extracting claims from handoff text, auto-verifying them against reality (filesystem, environment variables, script syntax, config parsing, pipeline outputs), and tracking how long unverified claims persist. Claims that fail verification get flagged; claims that linger without verification get marked stale. The gate runs at every agent handoff point, supplying the oracle bits that distinguish confabulation from understanding.
+
+The pipeline: **Extract** (scan for claims) → **Classify** (type + verifiability) → **Verify** (check against ground truth) → **Track** (SQLite persistence across runs) → **Report** (failures + staleness + tree health).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `confab gate` | Run the full cascade gate |
+| `confab check "text"` | Check inline text for claims |
+| `confab extract file.md` | Extract claims without verifying |
+| `confab quick` | One-line gate summary |
+| `confab prune` | Identify stale build sections to remove |
+| `confab sweep` | Show tracked claims by staleness |
+| `confab sweep --stats` | Tracker statistics |
+| `confab report` | System health dashboard (gate + supports + coverage) |
+| `confab init` | Generate a starter `confab.toml` |
+
+## Configuration
+
+`confab.toml` in your workspace root:
+
+```toml
+[confab]
+files_to_scan = ["docs/priorities.md", "notes/handoff.md"]
+stale_threshold = 3
+db_path = "confab_tracker.db"
+
+[confab.env_vars]
+known = ["OPENAI_API_KEY", "DATABASE_URL"]
+
+[confab.pipelines]
+"my_pipeline.py" = ["output/data/", "output/report.json"]
+
+# Optional: name-based pipeline matching for status claims
+[confab.pipeline_names]
+"data pipeline" = "my_pipeline.py"
+
+# Optional: count verification sources
+[confab.count_sources.my_entries]
+file = "data/entries.json"
+type = "json_array"
+json_path = "entries"
+
+[confab.count_sources.task_queue]
+file = "queue.md"
+type = "regex_count"
+pattern = "^###\\s+Task\\s+\\d+"
+rate_per_day = 3.0
+```
+
+Without a config file, the framework auto-detects context and uses sensible defaults.
+
+## Claim Types
+
+| Type | Example | Verification |
+|------|---------|-------------|
+| `file_exists` | "config.json is ready" | `os.path.exists()` |
+| `file_missing` | "output.csv doesn't exist" | `os.path.exists()` |
+| `env_var` | "blocked on OPENAI_API_KEY" | `.env` files + `os.environ` |
+| `pipeline_works` | "audio pipeline operational" | Output artifact check |
+| `pipeline_blocked` | "publishing blocked" | Output artifact check |
+| `script_runs` | "generate.py works" | `py_compile` + import check |
+| `config_present` | "settings.toml configured" | Parse + key check |
+| `count_claim` | "144 tests passing" | Source-specific count |
+
+## Architecture
+
+See [DESIGN.md](DESIGN.md) for the full architecture, including the cascade propagation problem, verification methods, and the gate's role at agent handoff points.
+
+## License
+
+MIT

confab_framework-0.3.0/__init__.py

@@ -0,0 +1,44 @@
+"""Confabulation Framework — structural detection and prevention for multi-agent systems.
+
+Solves the cascade propagation problem: agents state falsehoods confidently,
+other agents copy them forward indefinitely. This framework makes verification
+structural (enforced by code) rather than aspirational (suggested by docs).
+
+Quick start (CLI)::
+
+    pip install confab-framework
+    confab init                        # generate a confab.toml
+    confab gate                        # run the cascade gate
+
+Quick start (Python API)::
+
+    from confab import ConfabGate
+
+    gate = ConfabGate("confab.toml")
+    report = gate.run()
+
+    if report.has_failures:
+        print(report.format_report())
+
+See DESIGN.md for architecture.
+"""
+
+from .config import ConfabConfig, get_config, load_config, set_config
+from .gate import run_gate, quick_check, GateReport, ConfabGate
+from .claims import extract_claims, extract_claims_from_file, Claim, ClaimType
+from .verify import verify_claim, verify_all, VerificationResult, VerificationOutcome
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # High-level API
+    "ConfabGate",
+    # Configuration
+    "ConfabConfig", "get_config", "load_config", "set_config",
+    # Gate (function-based)
+    "run_gate", "quick_check", "GateReport",
+    # Claims
+    "extract_claims", "extract_claims_from_file", "Claim", "ClaimType",
+    # Verification
+    "verify_claim", "verify_all", "VerificationResult", "VerificationOutcome",
+]

confab_framework-0.3.0/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python -m confab gate"""
+from .cli import main
+
+main()