Metadata-Version: 2.4
Name: semantic-reasoning-graph
Version: 0.1.0
Summary: A semantic IR for reasoning structure with contract-enforced agentic execution and automatic evidence trails.
Author-email: Medulla Labs <bob@tribit.io>
License: Apache-2.0
Project-URL: Homepage, https://github.com/medullalabs/semantic-reasoning-graph
Project-URL: Repository, https://github.com/medullalabs/semantic-reasoning-graph
Project-URL: Issues, https://github.com/medullalabs/semantic-reasoning-graph/issues
Project-URL: Changelog, https://github.com/medullalabs/semantic-reasoning-graph/blob/main/CHANGELOG.md
Keywords: llm,agents,reasoning,semantic-graph,contracts,evidence,ir
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# SRG -- Semantic Reasoning Graph

[![PyPI](https://img.shields.io/pypi/v/semantic-reasoning-graph.svg)](https://pypi.org/project/semantic-reasoning-graph/)
[![Python versions](https://img.shields.io/pypi/pyversions/semantic-reasoning-graph.svg)](https://pypi.org/project/semantic-reasoning-graph/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![CI](https://github.com/medullalabs/semantic-reasoning-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/medullalabs/semantic-reasoning-graph/actions/workflows/ci.yml)

SRG is a **structural safety net for reasoning-centric systems**. It describes computation as typed nodes connected by explicit data-flow edges, with contract-enforced agentic execution and automatic evidence trails. Two node kinds: **deterministic** (pure Python functions) and **agentic** (LLM calls with JSON schema validation, contract checking, and automatic retry).

SRG's value is not making edits easier -- a capable LLM can edit Python equally well. The value is making edits **safer**: structural validation catches bugs (duplicate nodes, invalid edges, cycles, missing schemas) that Python silently accepts. Contracts prevent silent reasoning degradation. Evidence provides automatic, structured debugging without custom logging.

## What SRG gives you over plain Python

- **Contracts as infrastructure.** Declarative (`score in 0..100`), auto-enforced with retry, required on all agentic nodes. Not optional `if/raise` scattered across function bodies.
- **Structural validation.** `validate_graph()` catches duplicate nodes, invalid edges, cycles, and missing schemas before execution. Python lets these through as silent bugs or runtime exceptions.
- **Automatic evidence.** Every node execution emits an `EvidenceRecord` with timestamps, input/output hashes, attempt counts, and duration. No instrumentation needed.
- **Separation of policy from computation.** Graph topology, weights, contracts, and node types live in YAML. Computation lives in Python. Non-coders can review the reasoning structure.
- **Semantic diff.** `semantic_diff(old, new)` detects "node added", "contract changed", "edge rewired" -- structured changes, not line-level noise.
- **Composition.** `compose_graphs(a, b, connecting_edges)` merges graphs with validation.

## What SRG is NOT

- **Not more compact than Python.** SRG is ~1.7x larger (YAML + Python vs Python alone).
- **Not a productivity multiplier.** Adding a scoring factor takes more total lines in SRG.
- **Not a workflow engine.** No task queues, no scheduling, no DAG orchestration.
- **Not an adapter marketplace.** No plugin system, no connectors, no transports.
- **Not a reactive stream system.** No event streams, no pub/sub, no backpressure.
- **Not a replacement for Python.** SRG graphs describe reasoning structure; Python does the work.

## When to use SRG

Systems where **the cost of a silent reasoning bug exceeds the cost of framework overhead**:
- Scoring, decision, and assessment pipelines with LLM components
- Systems that will be iteratively modified (contracts catch regressions)
- Teams where non-coders need to review reasoning structure
- Systems that need audit trails without custom logging

## Install

```bash
pip install semantic-reasoning-graph
```

## Quick example

```yaml
name: subnet_scorer
nodes:
  - id: extract_features
    kind: deterministic
    inputs: [subnet_data]
    outputs: [mechanism_features, network_features, team_features]
    function_ref: extract_features

  - id: score_team_quality
    kind: agentic
    inputs: [team_features]
    outputs: [team_quality_score, team_quality_reasoning]
    prompt_template: |
      Assess team quality from GitHub metrics: {team_features}
      Return JSON with team_quality_score (0-100) and team_quality_reasoning.
    output_schema:
      type: object
      required: [team_quality_score, team_quality_reasoning]
      properties:
        team_quality_score: { type: number, minimum: 0, maximum: 100 }
        team_quality_reasoning: { type: string }
    contracts:
      - team_quality_score in 0..100
      - team_quality_reasoning is nonempty
    retry_policy:
      max_attempts: 2
      retry_on: [schema_failure, contract_failure]

  - id: aggregate_scores
    kind: deterministic
    inputs: [mechanism_score, network_score, team_quality_score]
    outputs: [overall_score]
    function_ref: aggregate_scores

edges:
  - from_node: extract_features
    to_node: score_team_quality
  - from_node: score_team_quality
    to_node: aggregate_scores
```

```python
from srg.runtime.loader import load_graph
from srg.runtime.graph_runner import run_graph
from srg.runtime.deterministic_registry import DeterministicRegistry
from srg.kernel.agentic_call import OllamaProvider

graph = load_graph("srg/examples/subnet_scorer.yaml")

registry = DeterministicRegistry()

@registry.register("extract_features")
def extract_features(state):
    data = state["subnet_data"]
    return {"mechanism_features": ..., "network_features": ..., "team_features": ...}

@registry.register("aggregate_scores")
def aggregate_scores(state):
    return {"overall_score": state["team_quality_score"] * 0.15 + ...}

result = run_graph(
    graph, registry,
    llm_provider=OllamaProvider(model="qwen2.5:7b"),
    inputs={"subnet_data": {...}},
)

print(result.status)                    # "success"
print(result.outputs["overall_score"])  # 78.09
print(result.evidence_summary)          # {total_nodes: 7, passed: 7, ...}
```

## CLI

```bash
srg validate graph.yaml           # Validate structure + show execution order
srg run graph.yaml --provider ollama --model qwen2.5:7b --input '{"key": "val"}'
srg diff old.yaml new.yaml        # Semantic diff between two graphs
```

## Running tests

```bash
pip install -e ".[dev]"
pytest tests/ -v          # 281 tests
ruff check srg/ tests/    # Lint
mypy srg/                 # Type check (strict)
```

## Benchmarks

```bash
python benchmarks/token_benchmark.py          # SRG vs Python token efficiency
python benchmarks/llm_editing_experiment.py   # LLM editing: SRG vs Python (5 tasks)
python benchmarks/evidence_debugging_demo.py  # Evidence vs logging (3 scenarios)
```

## Specification

See `docs/srg_spec_v0_3.md` for the full specification, `docs/srg_conformance_v0_3.md` for the conformance checklist, and `docs/SRG_RUTHLESS_REVIEW_RUBRIC.md` for the evaluation rubric.
