py-brs 1.5.0

Belief Revision System - A maximally general framework for managing and revising belief systems

Belief Revision System (BRS)

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

Mermaid source

```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:

pip install -e .

Quick Start

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:

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

# 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