bulla 0.7.0__tar.gz

bulla-0.7.0/.github/workflows/bulla.yml

@@ -0,0 +1,54 @@
+name: bulla
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  coherence-check:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install bulla from source
+        run: pip install -e .
+
+      - name: Run bulla on bundled examples
+        run: |
+          bulla check --max-blind-spots 5 --format sarif compositions/ > bulla.sarif 2>/dev/null || true
+          bulla check --max-blind-spots 5 compositions/
+
+      - name: Upload SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: bulla.sarif
+        continue-on-error: true
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[ots]"
+          pip install pytest
+
+      - name: Run tests
+        run: python -m pytest tests/ -v

bulla-0.7.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/

bulla-0.7.0/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+## 0.7.0
+
+### Changed
+- **Renamed from `seam-lint` to `bulla`** — the package, CLI, Python imports, and all public API names now use the `bulla` identity. SEAM remains the name for the underlying theory; Bulla is the protocol and tool; Glyph is the company.
+- `SeamGuard` → `BullaGuard`, `SeamCheckError` → `BullaCheckError`
+- `to_seam_patch()` → `to_bulla_patch()`, `seam_patch_version` → `bulla_patch_version`
+- `seam_manifest` YAML key → `bulla_manifest` (parser accepts both for one version cycle)
+- MCP server tools: `bulla.witness`, `bulla.bridge`; resource URI: `bulla://taxonomy`
+- CLI entry point: `bulla` (was `seam-lint`)
+- SARIF rule IDs: `bulla/blind-spot`, `bulla/bridge-recommendation`
+- PyPI package: `pip install bulla`
+
+## 0.6.0
+
+### Added
+- **Witness kernel** (`witness.py`): deterministic measurement → receipt pipeline with three-layer separation (measurement / binding / judgment)
+- **Constitutional objects**: `Disposition` enum (5 levels), `BridgePatch` (frozen, Bulla Patch v0.1), `WitnessReceipt` (content-addressable, tamper-evident)
+- **`bulla serve`** — MCP stdio server exposing 2 tools + 1 resource:
+  - `bulla.witness`: composition YAML → WitnessReceipt (atomic measure-bind-judge)
+  - `bulla.bridge`: composition YAML → patched composition + receipt + before/after metrics
+  - `bulla.taxonomy` resource: convention taxonomy for agent inspection
+- **`bulla bridge`** — auto-generate bridged composition YAML or Bulla Patches from diagnosed composition
+- **`bulla witness`** — diagnose and emit WitnessReceipt as JSON
+- **`Diagnostic.content_hash()`** — deterministic SHA-256 of measurement content (excludes timestamps)
+- **`load_composition(text=)`** — parser accepts string input for MCP server use
+- **Policy profile**: `witness()` and `_resolve_disposition()` accept named `policy_profile` parameter (default: `witness.default.v1`), recorded in receipt and receipt hash
+- **Bulla Patch v0.1**: `BridgePatch.to_bulla_patch()` — explicitly typed patch format, not RFC 6902
+- **Typed error vocabulary**: `WitnessErrorCode` enum (4 codes), `WitnessError` exception
+- **Anti-reflexivity enforcement**: AST-level test proves `diagnostic.py` has zero imports from `witness.py` (Law 1); bounded recursion via `depth` parameter with `MAX_DEPTH=10` (Law 7)
+- **Three-hash boundary**: `composition_hash` (what was proposed), `diagnostic_hash` (what was measured), `receipt_hash` (what was witnessed) — tested for independence
+- 33 new tests (233 total)
+
+### Fixed
+- **Bridge generation bug**: when `from_field != to_field` and both sides hidden, destination tool received wrong field. Now generates separate Bridge per side with correct field.
+
+### Changed
+- `to_json_patch()` renamed to `to_bulla_patch()` with `bulla_patch_version: "0.1.0"` field
+- `receipt_hash` docstring documents timestamp inclusion semantics (unique event identity vs deduplication via `diagnostic_hash`)
+- Bridge response includes `original_composition_hash` for traceability
+
+## 0.5.0
+
+### Added
+- **Three-tier confidence: "unknown" tier now live** — single description-keyword-only or weak schema signals (enum partial overlap, integer type inference) now correctly produce `unknown` instead of the dead-branch `inferred`
+- **0-100 range disambiguation** — fields with `minimum: 0, maximum: 100` now check field name and description for rate/percent indicators before choosing `rate_scale` vs `score_range`
+- **Domain-aware prioritization** — `classify_tool_rich()` accepts `domain_hint` (e.g. `"financial"`, `"ml"`) to boost domain-relevant dimensions from `unknown` → `inferred`
+- **`_normalize_enum_value()` helper** — single source of truth for enum normalization (lowercase, strip hyphens/underscores), replacing duplicated inline logic
+- **Real MCP validation suite** — 5 realistic tool definitions (Stripe, GitHub, Datadog, Slack, ML) with per-tool coverage assertions
+- **End-to-end coverage test** — real MCP JSON → generate manifests → validate → assert ≥6/10 dimensions detected
+- **Domain map API** — `_get_domain_map()` loads taxonomy `domains` metadata (previously defined but unused)
+- 16 new tests covering unknown tier, range disambiguation, domain boosting, normalization, real-tool coverage, and E2E pipeline (178 total)
+
+### Changed
+- `_merge_signals()` accepts `domain_hint` parameter for confidence boosting
+- `classify_tool_rich()` accepts `domain_hint` parameter (backward-compatible, defaults to `None`)
+- Description-only signals now produce `unknown` confidence (was incorrectly `inferred`)
+
+### Fixed
+- Dead `else` branch in `_merge_signals()` — the "unknown" confidence tier was unreachable (all paths produced "inferred")
+- Field name propagation for description hits in `_merge_signals()` — description hits now inherit field names from co-occurring name/schema hits
+- Circular import between `classifier.py` and `mcp.py` now documented with inline comment
+- False positive: `format: "uri"` / `"email"` / `"uri-reference"` no longer mapped to `encoding` dimension — these are string formats, not encoding conventions
+- False positive: `count` removed from `id_offset` field name patterns — count is a quantity, not an index
+- Text formatter now explains fee-vs-blind-spots divergence when fee = 0 but blind spots exist
+
+## 0.4.0
+
+### Added
+- **Multi-signal convention inference**: classifier now uses three independent signal sources instead of field-name regex alone
+  - Signal 1: Field name pattern matching (existing, now taxonomy-compiled)
+  - Signal 2: Description keyword matching — detects conventions from tool/field descriptions (e.g. "amounts in cents", "ISO-8601 timestamps")
+  - Signal 3: JSON Schema structural signals — `format`, `type`+range, `enum`, `pattern` metadata
+- **Nested property extraction**: recursive extraction of fields from nested JSON Schema objects with dot-path naming (e.g. `invoice.total_amount`), depth limit 3
+- **Taxonomy as single source of truth**: `field_patterns` from `taxonomy.yaml` now compile into classifier regex at load time; `known_values` drive enum matching
+- **Three-tier confidence model**: `declared` (2+ independent signals agree), `inferred` (1 strong signal), `unknown` (weak/ambiguous) — replaces the binary high/medium system
+- `FieldInfo` dataclass for rich field metadata (type, format, enum, min/max, pattern, description)
+- `classify_tool_rich()` high-level API for full multi-signal classification of MCP tool definitions
+- `classify_description()` for extracting dimension signals from tool descriptions
+- `classify_schema_signal()` for extracting dimension signals from JSON Schema metadata
+- `description_keywords` per dimension in taxonomy (v0.2)
+- Currency codes (USD, EUR, GBP, JPY, CNY, BTC) added to `amount_unit` known_values
+- `extract_field_infos()` public API for rich field extraction from tool schemas
+- Manifest generation now uses multi-signal classifier with `sources` metadata in output
+- 41 new tests covering all signal types, confidence tiers, and round-trip validation (162 total)
+
+### Changed
+- Confidence values in generated manifests are now directly `declared`/`inferred`/`unknown` — the `_CONFIDENCE_MAP` translation layer is removed
+- `infer_from_manifest()` output now includes signal sources in review comments
+- Taxonomy version bumped to 0.2
+
+### Fixed
+- Version string tests now use `__version__` import instead of hardcoded values
+
+## 0.3.0
+
+### Added
+- `bulla manifest --publish` — anchor manifest commitment hash to Bitcoin timechain via OpenTimestamps
+- `bulla manifest --verify` — verify OTS proof on a published manifest
+- `bulla manifest --verify --upgrade` — upgrade pending proofs to confirmed after Bitcoin block inclusion
+- Optional `[ots]` extra: `pip install bulla[ots]` (base install stays single-dependency)
+- Commitment hash excludes OTS fields for deterministic verification after publish
+- 11 new OTS tests (mocked calendars, no network required)
+
+## 0.2.0
+
+### Added
+- `bulla manifest` — generate and validate Bulla Manifest files from MCP tool definitions
+- `bulla manifest --from-json` — generate from MCP manifest JSON
+- `bulla manifest --from-server` — generate from live MCP server
+- `bulla manifest --validate` — validate existing manifest YAML
+- `bulla manifest --examples` — generate example manifests to see the format
+- `bulla scan` — scan live MCP server(s) via stdio and diagnose
+- `bulla init` — interactive wizard to generate a composition YAML
+- `bulla diagnose --brief` — one-line-per-file summary output
+- `BullaGuard` Python API for programmatic composition analysis
+- Convention taxonomy (10 dimensions) with field-pattern inference
+- Auto-validation after manifest generation
+- "Now what?" guidance in `check` output on failure
+- Quickstart guide when running bare `bulla` with no subcommand
+- SARIF output format for GitHub Code Scanning integration
+
+### Fixed
+- Confidence mapping: classifier internal grades (`high`/`medium`) now correctly map to manifest spec vocabulary (`declared`/`inferred`/`unknown`)
+- `_examples_dir()` portability for installed packages
+
+## 0.1.0
+
+### Added
+- `bulla diagnose` — full sheaf cohomology diagnostic with blind spot detection
+- `bulla check` — CI/CD gate with configurable thresholds
+- `bulla infer` — infer proto-composition from MCP manifest JSON
+- Text, JSON, and SARIF output formats
+- Exact rational arithmetic (no floating-point) via Python `Fraction`
+- 9 bundled example compositions (financial, code review, ETL, RAG, auth, MCP)
+- 107 tests, single dependency (PyYAML)

bulla-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Res Agentica
+
+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.

bulla-0.7.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: bulla
+Version: 0.7.0
+Summary: Witness kernel for agent tool compositions — diagnose, attest, seal
+Project-URL: Homepage, https://github.com/jkomkov/bulla
+Project-URL: Issues, https://github.com/jkomkov/bulla/issues
+Author: Glyph
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,bulla,coherence,composition,mcp,witness
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: ots
+Requires-Dist: opentimestamps-client>=0.7; extra == 'ots'
+Description-Content-Type: text/markdown
+
+# bulla
+
+Witness kernel for agent tool compositions — diagnose, attest, seal. Finds semantic blind spots that bilateral verification cannot reach and recommends bridge annotations to eliminate them.
+
+**Zero heavy dependencies.** Only requires PyYAML. No numpy, no scipy, no LLM calls. Installs in under a second.
+
+> **Naming**: *Bulla* is the protocol and tool. *SEAM* is the underlying theory (see [The Seam Protocol](../papers/seam/)). *Glyph* is the company.
+
+## Install
+
+```bash
+pip install bulla
+```
+
+## Quick start
+
+Run the built-in examples to see output immediately:
+
+```bash
+bulla diagnose --examples
+```
+
+Diagnose your own composition:
+
+```bash
+bulla diagnose my_pipeline.yaml
+```
+
+## Library API
+
+`BullaGuard` is the primary programmatic interface. Use it to embed coherence analysis in any Python application, agent framework, or CI pipeline.
+
+```python
+from bulla import BullaGuard, BullaCheckError
+
+# Path A: From raw tool definitions (the framework integration path)
+guard = BullaGuard.from_tools({
+    "invoice_parser": {
+        "fields": ["total_amount", "due_date", "line_items", "currency"],
+        "conventions": {"amount_unit": "dollars", "date_format": "ISO-8601"},
+    },
+    "settlement_engine": {
+        "fields": ["amount", "settlement_date", "ledger_entry"],
+        "conventions": {"amount_unit": "cents"},
+    },
+}, edges=[("invoice_parser", "settlement_engine")])
+
+# Path B: From MCP manifest JSON
+guard = BullaGuard.from_mcp_manifest("manifest.json")
+
+# Path C: From YAML composition (the v0.1 path)
+guard = BullaGuard.from_composition("pipeline.yaml")
+
+# Path D: From a live MCP server via stdio
+guard = BullaGuard.from_mcp_server("python my_server.py")
+
+# Diagnose
+diag = guard.diagnose()
+diag.coherence_fee         # int
+diag.blind_spots           # list[BlindSpot]
+diag.bridges               # list[Bridge]
+
+# Check (raises BullaCheckError if thresholds exceeded)
+guard.check(max_blind_spots=0, max_unbridged=0)
+
+# Export
+guard.to_yaml("pipeline.yaml")   # save for CI
+guard.to_json()                   # JSON string with version + hash
+guard.to_sarif()                  # SARIF string
+```
+
+### Framework integration example
+
+A LangChain integration becomes:
+
+```python
+from bulla import BullaGuard
+
+class BullaCoherenceCallback(BaseCallbackHandler):
+    def on_chain_start(self, serialized, inputs, **kwargs):
+        tools = extract_tools_from_chain(serialized)
+        guard = BullaGuard.from_tools(tools)
+        diag = guard.diagnose()
+        if diag.coherence_fee > 0:
+            warnings.warn(f"Composition has {len(diag.blind_spots)} blind spots")
+```
+
+## What it does
+
+When tools in a pipeline share implicit conventions (date formats, unit scales, encoding schemes), some of those conventions may be invisible to bilateral verification -- each pair of tools looks correct in isolation, but the pipeline as a whole can silently produce wrong results.
+
+bulla computes the **coherence fee**: the number of independent semantic dimensions that fall through the cracks of pairwise checks. For each blind spot, it recommends a **bridge** -- a specific field to expose in the tool's observable schema.
+
+```
+  Financial Analysis Pipeline
+  ═══════════════════════════
+
+  Topology: 3 tools, 3 edges, beta_1 = 1
+
+  Blind spots (2):
+    [1] day_conv_match (data_provider -> financial_analysis)
+        day_convention hidden on both sides
+    [2] metric_type_match (financial_analysis -> portfolio_verification)
+        risk_metric hidden on both sides
+
+  Recommended bridges:
+    [1] Add 'day_convention' to F(data_provider) and F(financial_analysis)
+    [2] Add 'risk_metric' to F(financial_analysis) and F(portfolio_verification)
+
+  After bridging: fee = 0
+```
+
+## Composition format
+
+Compositions are YAML files that describe your tool pipeline. See [`composition-schema.json`](composition-schema.json) for the full schema.
+
+```yaml
+name: My Pipeline
+
+tools:
+  tool_a:
+    internal_state: [field_x, field_y, hidden_z]
+    observable_schema: [field_x, field_y]
+
+  tool_b:
+    internal_state: [field_x, hidden_z]
+    observable_schema: [field_x]
+
+edges:
+  - from: tool_a
+    to: tool_b
+    dimensions:
+      - name: x_match
+        from_field: field_x
+        to_field: field_x
+      - name: z_match
+        from_field: hidden_z
+        to_field: hidden_z
+```
+
+- **`internal_state`**: All semantic dimensions the tool operates on internally (the full stalk S(v)).
+- **`observable_schema`**: Dimensions visible in the tool's API (the observable sub-sheaf F(v)). Must be a subset of `internal_state`.
+- **`edges`**: Bilateral interfaces between tools. Each dimension names a shared convention.
+
+A dimension is a **blind spot** when `from_field` or `to_field` is in `internal_state` but not in `observable_schema` of the respective tool.
+
+## Commands
+
+### `bulla diagnose`
+
+Diagnose compositions and report blind spots, bridges, and the coherence fee.
+
+```bash
+bulla diagnose pipeline.yaml                    # text output
+bulla diagnose --format json pipeline.yaml      # JSON with version + SHA-256
+bulla diagnose --format sarif pipeline.yaml     # SARIF for GitHub code scanning
+bulla diagnose --examples                       # run on bundled examples
+```
+
+### `bulla check`
+
+CI/CD gate. Exits with code 1 if any composition exceeds the specified thresholds.
+
+```bash
+bulla check pipeline.yaml                                   # default: --max-blind-spots 0 --max-unbridged 0
+bulla check --max-blind-spots 2 compositions/               # allow up to 2 blind spots
+bulla check --format sarif compositions/ > results.sarif    # SARIF for GitHub Actions
+```
+
+### `bulla scan`
+
+Scan live MCP servers via stdio. Zero configuration — no YAML required.
+
+```bash
+bulla scan "python my_server.py"                             # single server
+bulla scan "python server_a.py" "python server_b.py"         # multi-server composition
+bulla scan "python server.py" -o pipeline.yaml               # save for CI
+bulla scan "python server.py" --format json                  # JSON diagnostic
+```
+
+The scanner spawns each server as a subprocess, performs the MCP initialize handshake, queries `tools/list`, and auto-generates a composition using the heuristic dimension classifier. No MCP SDK dependency.
+
+### `bulla manifest`
+
+Generate or validate [Bulla Manifest](bulla-manifest-spec-v0.1.md) files.
+
+```bash
+bulla manifest --from-json tools.json -o manifest.yaml       # from MCP manifest JSON
+bulla manifest --from-server "python server.py"              # from live MCP server
+bulla manifest --validate manifest.yaml                      # validate against spec
+```
+
+### `bulla init`
+
+Interactive wizard to generate a composition YAML.
+
+```bash
+bulla init
+bulla init -o my_pipeline.yaml
+```
+
+### `bulla infer`
+
+Infer a proto-composition from an MCP manifest JSON.
+
+```bash
+bulla infer manifest.json                # stdout
+bulla infer manifest.json -o proto.yaml  # save to file
+```
+
+### `bulla --version`
+
+Print the installed version.
+
+## Bulla Manifest Specification
+
+The [Bulla Manifest Spec v0.1](bulla-manifest-spec-v0.1.md) defines a per-tool convention declaration format. Each manifest declares what semantic conventions a single tool assumes (e.g. "amounts are in dollars", "dates are ISO-8601").
+
+See the [spec](bulla-manifest-spec-v0.1.md), [JSON Schema](bulla-manifest-schema.json), and the built-in [taxonomy](src/bulla/taxonomy.yaml) of 10 convention dimensions.
+
+## CI integration
+
+### GitHub Actions with SARIF
+
+```yaml
+name: bulla
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install bulla
+      - run: bulla check --format sarif compositions/ > bulla.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: bulla.sarif
+```
+
+This uploads results to GitHub's code scanning tab, where blind spots appear as annotations on pull requests.
+
+### Simple pass/fail
+
+```yaml
+      - run: pip install bulla
+      - run: bulla check compositions/
+```
+
+## Output formats
+
+| Format | Flag | Use case |
+|--------|------|----------|
+| Text | `--format text` (default) | Developer terminal |
+| JSON | `--format json` | Orchestrator integration, includes version + SHA-256 |
+| SARIF | `--format sarif` | GitHub code scanning, VS Code SARIF viewer |
+
+## How it works
+
+bulla builds a discrete coboundary operator (delta-0) from C^0 (tool dimensions) to C^1 (edge dimensions) for both the observable sheaf F and the full sheaf S. The coherence fee is:
+
+```
+fee = H^1(F_obs) - H^1(F_full)
+    = (dim C^1 - rank delta_obs) - (dim C^1 - rank delta_full)
+    = rank delta_full - rank delta_obs
+```
+
+Each unit of fee corresponds to an independent semantic dimension that bilateral verification cannot detect. Bridging (exposing hidden fields in the observable schema) increases rank(delta_obs) until it matches rank(delta_full).
+
+The rank computation uses exact arithmetic (Python's `fractions.Fraction` module) via Gaussian elimination -- no floating-point tolerance, no numpy dependency.
+
+## License
+
+MIT