py-brs 2.0.0
Belief Revision System - A maximally general framework for managing and revising belief systems
License: MIT
Requires Python: >=3.9
Keywords: belief revision, knowledge management, cross-domain reasoning, pattern matching, hypothesis testing

# Belief Revision System (BRS)

[![PyPI version](https://img.shields.io/pypi/v/py-brs.svg)](https://pypi.org/project/py-brs/)
[![Python versions](https://img.shields.io/pypi/pyversions/py-brs.svg)](https://pypi.org/project/py-brs/)
[![License](https://img.shields.io/pypi/l/py-brs.svg)](https://github.com/egoughnour/brs/blob/main/LICENSE)
[![Release](https://img.shields.io/github/actions/workflow/status/egoughnour/brs/release.yml?label=release)](https://github.com/egoughnour/brs/actions/workflows/release.yml)

A maximally general framework for managing, revising, and reasoning about belief systems.

## Overview

BRS provides domain-agnostic infrastructure for:

- **Versioned Knowledge Graphs**: Immutable, content-addressable storage of nodes, edges, patterns, and world bundles
- **Cross-Domain Discovery**: Pattern matching via pluggable similarity metrics to find analogies between domains
- **Non-Destructive Evaluation**: Shadow worlds for hypothesis testing without affecting canonical beliefs
- **Pluggable Domain Extensions**: Auto-discovered smoke tests and domain-specific validators


![Architecture](https://raw.githubusercontent.com/egoughnour/brs/main/docs/architecture.png)

<details>
<summary>Mermaid source</summary>

```mermaid
graph TD
    subgraph Extensions["Domain Extensions"]
        W["Writing_smoke.py"]
        B["Biology_smoke.py"]
        Y["Your Domain_smoke.py"]
    end

    W & B & Y --> R["Registry(auto-discovery)"]

    subgraph Core["Core Framework"]
        R --> E["Evaluator(smoke tests)"]
        D["Discovery(mesh/sim)"] --> E
        E --> D
        E --> V["Revision(shadow)"]
        V --> E
        D & E & V --> I["Inference(graph traversal)"]
        I --> S["Storage(CAS + SQLite)"]
        S --> C["Core(types + utilities)"]
    end
```

</details>

## Installation

```bash
pip install py-brs
```

For development:

```bash
pip install -e .
```

## Quick Start

```python
from pathlib import Path
from brs import CASStore, Node, Edge, Pattern, WorldBundle

# Initialize storage
store = CASStore(Path("./my_knowledge_base"))

# Create a node
node = Node(
    id="CONCEPT_A",
    name="My Concept",
    node_type="primary",
    properties={"category": "example"}
)
h = store.put_object("Node", node)
store.upsert_node(node.id, node.name, h)

# Create an edge
edge = Edge(
    id="EDGE_1",
    parent_id="ROOT",
    child_id="CONCEPT_A",
    relation="derived_from",
    tier=0,
    confidence=0.95
)
h = store.put_object("Edge", edge)
store.upsert_edge(edge.id, edge.parent_id, edge.child_id,
                  edge.relation, edge.tier, edge.confidence, h)

# Create a world bundle
world = WorldBundle(
    domain_id="my_domain",
    version_label="green",
    node_ids=("ROOT", "CONCEPT_A"),
    edge_ids=("EDGE_1",),
    evidence_ids=(),
    pattern_ids=(),
    created_utc="2025-01-27T00:00:00Z"
)
store.put_world(world)

# Query ancestry
from brs import best_path_to_any_root
result = best_path_to_any_root(store, "CONCEPT_A", ["ROOT"])
print(result.explanation)

store.close()
```

## Key Concepts

### World Bundles
Immutable snapshots of a domain's belief state. Multiple versions can coexist (e.g., "green" for canonical, "_shadow_eval" for testing).

### Patterns
Capture invariants and operators that should hold across the domain. Used for cross-domain analog discovery.

### Mesh Discovery
Find analogies between domains by comparing pattern signatures using Jaccard similarity or custom metrics.

### Shadow Evaluation
Fork a world, apply a proposed change, run smoke tests, and compare maturity—all without affecting canonical beliefs.

## Creating Domain Extensions

Add a file `brs/domains/my_domain_smoke.py`:

```python
DOMAIN_ID = "my_domain"

def run(store, domain_id, world_label):
    """Smoke tests for my domain."""
    tests, failures, messages = 0, 0, []

    # Your invariant checks here
    tests += 1
    # if check_something_fails:
    #     failures += 1
    #     messages.append("FAIL: ...")
    # else:
    messages.append("OK: Domain invariants hold")

    return (tests, failures, messages)

SMOKE_LEVELS = {
    "smoke": run,        # Fast checks
    "regression": run,   # Medium checks
    "deep": run,         # Expensive checks
}
```

The domain will be auto-discovered and registered when the `brs.domains` package is imported.

## CLI Usage

```bash
# List worlds
brs worlds

# Show domain statistics
brs stats my_domain

# Run smoke tests
brs smoke my_domain --level smoke --verbose

# Discover cross-domain analogs
brs discover domain_a domain_b --min-score 0.3

# Evaluate a proposal
brs evaluate PROPOSAL_ID my_domain --verbose
```

## Components

| Module | Purpose |
|--------|---------|
| `core` | Type definitions (Node, Edge, Pattern, WorldBundle, Maturity) |
| `storage` | Content-addressable SQLite backend |
| `mesh` | Pattern signatures and similarity metrics |
| `inference` | Graph traversal (ancestry, reachability) |
| `revision` | Shadow imports and evaluation |
| `discovery` | Cross-domain analog suggestion |
| `evaluator` | Smoke test orchestration |
| `domains` | Auto-discovered domain extensions |
| `cli` | Command-line interface |


## License

MIT