semantic-compiler-core 0.2.0

Deterministic semantic compiler core: SIR → RLang → ProofBundle with stable hashes.

semantic-compiler-core

Deterministic Reasoning Compiler for Verifiable AI Systems

A production-grade compiler that transforms structured decision logic (SIR) into cryptographically verifiable proof bundles. Designed for enterprise compliance, rule engines, and provable AI pipelines where reproducibility and auditability are critical.

---

Overview

semantic-compiler-core is a deterministic reasoning compiler that converts Semantic Intermediate Representation (SIR) into RLang source code, then compiles and executes it to produce stable, hash-verified proof bundles. The compiler guarantees:

• Deterministic execution: Same input → same output, every time
• Cryptographic verification: Stable hashing (HMASTER, H_IR, HRICH) ensures reproducibility
• Zero nondeterministic IO: Pure deterministic compilation pipeline
• Clean architecture: Separation of stochastic (LLM) and deterministic layers

The compiler operates entirely offline and requires no API keys or external services. LLM frontend functionality is available separately in the nl_frontend package.

---

Why This Matters

Deterministic Execution in AI Pipelines

Traditional AI systems suffer from nondeterminism, making it impossible to verify decisions or reproduce results. semantic-compiler-core provides a deterministic foundation for:

• Verifiable decision-making: Every decision produces a cryptographic proof
• Enterprise compliance: Full audit trail with traceable reasoning
• Reproducible AI: Same logic + same input = same output, guaranteed
• Anti-hallucination pipelines: LLM proposes, deterministic logic disposes

Unique Proof Bundle Hashing

The compiler generates three cryptographic hashes:

• HMASTER: Program IR hash (proves the logic itself)
• H_IR: Intermediate representation hash
• HRICH: Execution trace hash (proves the execution path)

These hashes enable:

• Cryptographic verification of decision logic
• Blockchain-compatible proof generation (BoR - Blockchain of Reasoning)
• Tamper-proof audit logs
• Cross-system reproducibility verification

Clear Separation of Concerns

┌─────────────────────────────────────┐
│  Stochastic Layer (Optional)        │
│  nl_frontend/ (LLM → SIR)           │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  Deterministic Layer (Core)          │
│  SIR → RLang → IR → ProofBundle      │
│  Zero nondeterminism                │
└─────────────────────────────────────┘

---

Architecture Overview

The compiler follows a clean, layered architecture:

nl_frontend/ (optional)
│  • init_llm.py
│  • llm_bridge.py
│  • semantic_agent.py
│
↓  (LLM → SIR)
│
semantic_compiler/
│  • sir_model.py          ← SIR data structures
│  • sir_validator.py      ← SIR validation
│  • sir_to_rlang.py       ← SIR → RLang compiler
│  • rlang_runtime.py      ← RLang execution wrapper
│
↓  (SIR → RLang → IR → ProofBundle)
│
semantic_compiler_core/
│  • api.py                ← Public API
│  • version.py            ← Version info
│
↓
│
Deterministic Proof Layer
│  • HMASTER (program hash)
│  • H_IR (IR hash)
│  • HRICH (execution trace hash)
│  • TRP (Trace of Reasoning Process)

Layer Descriptions

1. SIR Model (sir_model.py): Defines the Semantic Intermediate Representation as strongly-typed Python dataclasses. SIR v0.1 supports scalar integer decision pipelines with comparison operators and Boolean combiners.

2. SIR Validator (sir_validator.py): Validates SIR structure and enforces semantic constraints. Ensures type safety and rejects invalid constructs.

3. SIR → RLang Compiler (sir_to_rlang.py): Deterministically compiles SIR to RLang source code. Guarantees byte-for-byte identical output for identical input.

4. RLang Runtime (rlang_runtime.py): Wraps the rlang-compiler PyPI package to execute RLang code and generate proof bundles. Handles IR canonicalization and hash extraction.

5. Public API (api.py): Clean, stable API surface:

   • compile_sir_to_proof(): One-shot SIR → ProofBundle compilation
   • sir_to_rlang(): SIR → RLang source code
   • run_with_proof(): RLang → ProofBundle execution

---

Key Features

• ✅ Pure deterministic compiler core: Zero external dependencies beyond deterministic modules
• ✅ Strict validation mode: Enforces type safety and semantic correctness
• ✅ Stable hashing: HMASTER, H_IR, HRICH guarantee reproducibility
• ✅ Strong typing: Canonical JSON with dataclass validation
• ✅ Works offline: No API keys, no network calls, no nondeterministic IO
• ✅ Production-grade packaging: Proper PyPI distribution with CI/CD
• ✅ Clean separation: LLM frontend is optional and separated

---

Installation

pip install semantic-compiler-core

Requirements

• Python >= 3.9
• rlang-compiler >= 0.2.1 (automatically installed)

---

Quick Start

Minimal Example

from semantic_compiler_core import compile_sir_to_proof

# Define a simple decision pipeline in SIR format
sir = {
    "type": "DecisionPipeline",
    "name": "main",
    "input_name": "value",
    "steps": [
        {
            "type": "Decision",
            "condition": {"op": "gt", "args": ["value", 10]},
            "then_steps": [{"type": "SetOutput", "value": 1}],
            "else_steps": [{"type": "SetOutput", "value": 0}],
        }
    ]
}

# Compile SIR to proof bundle
bundle = compile_sir_to_proof(sir, input_value=15)

# Access cryptographic hashes
print(f"HMASTER: {bundle['hashes']['HMASTER']}")
print(f"HRICH: {bundle['hashes']['HRICH']}")

# Access execution result
print(f"Output: {bundle['bundle']['output']}")

Step-by-Step API Usage

from semantic_compiler_core import sir_to_rlang, run_with_proof

# Step 1: SIR → RLang source code
rlang_source = sir_to_rlang(sir)
print(rlang_source)

# Step 2: Execute RLang and generate proof bundle
result = run_with_proof(rlang_source, input_value=15)
print(result['hashes']['HMASTER'])

---

Use Cases

For Investors

• Verified AI decision systems: Cryptographically provable AI logic
• Compliance automation: Regulatory-compliant rule engines with audit trails
• Blockchain integration: BoR-compatible proof generation for on-chain verification
• Enterprise AI governance: Transparent, auditable decision-making systems

For Enterprises

• Rule engines with cryptographic proofs: Financial compliance, healthcare regulations
• Deterministic workflow automation: Reproducible business logic execution
• Audit trail generation: Tamper-proof logs with cryptographic verification
• Anti-hallucination LLM pipelines: "AI proposes, Logic disposes" architectures

For Developers

• Provable AI systems: Build verifiable machine learning pipelines
• Deterministic testing: Reproducible test execution with proof generation
• Reasoning engines: Structured decision logic with cryptographic guarantees
• Compliance tooling: Regulatory logic with full traceability

---

Current Scope (SIR v0.1)

The compiler currently supports:

• Input: Single scalar integer (Int)
• Operators: gt, ge, lt, le, eq, neq
• Boolean combiners: all(), any(), not()
• Output: Scalar constant integers

Deterministic Guarantees

For any valid SIR v0.1 pipeline and input value:

• Same input → same SIR representation
• Same SIR → same RLang source code (byte-for-byte identical)
• Same RLang → same canonical IR
• Same IR → same execution trace (TRP)
• Same execution → same proof bundle (HMASTER, HRICH)

---

Roadmap (v0.3 and Beyond)

• Records: Multi-field input types ({income: Int, age: Int})
• Lists: Array/vector operations
• Pattern Matching: Advanced control flow constructs
• Modules: Code organization and reuse
• Deterministic Arithmetic Engine: Extended mathematical operations
• Decision DAGs: Graph-based execution models
• Graph Execution: Parallel decision path evaluation

---

Development

Local Installation

git clone <repository-url>
cd Verifiable_agent
pip install -e .

Running Tests

pytest tests/

Building Distribution

python -m build

---

License

[Specify your license here]

---

Authors

[Specify authors here]

---

Contributing

Contributions welcome! Please ensure all tests pass and deterministic guarantees are maintained.

---

Links

• PyPI: https://pypi.org/project/semantic-compiler-core/
• Source: https://github.com/kushagrab21/Compiler_new
• Issues: https://github.com/kushagrab21/Compiler_new/issues