py-brs 1.0.1

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

Architecture

┌────────────────────────────────────────────────────────────────────┐
│                         Domain Extensions                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │   Writing    │  │   Biology    │  │  Your Domain │             │
│  │  _smoke.py   │  │  _smoke.py   │  │  _smoke.py   │             │
│  └──────────────┘  └──────────────┘  └──────────────┘             │
│           │               │               │                        │
│           └───────────────┴───────────────┘                        │
│                           │                                        │
│                    ┌──────▼──────┐                                 │
│                    │  Registry   │  (auto-discovery)               │
│                    └──────┬──────┘                                 │
├────────────────────────────┼───────────────────────────────────────┤
│                            │                                       │
│  ┌──────────────┐  ┌───────▼──────┐  ┌──────────────┐             │
│  │  Discovery   │──│  Evaluator   │──│   Revision   │             │
│  │  (mesh/sim)  │  │ (smoke tests)│  │   (shadow)   │             │
│  └──────────────┘  └──────────────┘  └──────────────┘             │
│           │               │               │                        │
│           └───────────────┴───────────────┘                        │
│                           │                                        │
│                    ┌──────▼──────┐                                 │
│                    │  Inference  │  (graph traversal)              │
│                    └──────┬──────┘                                 │
│                           │                                        │
│                    ┌──────▼──────┐                                 │
│                    │   Storage   │  (CAS + SQLite)                 │
│                    └──────┬──────┘                                 │
│                           │                                        │
│                    ┌──────▼──────┐                                 │
│                    │    Core     │  (types + utilities)            │
│                    └─────────────┘                                 │
└────────────────────────────────────────────────────────────────────┘

Installation

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