Metadata-Version: 2.4
Name: semantic-compiler-core
Version: 0.2.0
Summary: Deterministic semantic compiler core: SIR → RLang → ProofBundle with stable hashes.
Author-email: YOUR NAME <you@example.com>
Project-URL: Homepage, https://github.com/kushagrab21/Compiler_new
Project-URL: Source, https://github.com/kushagrab21/Compiler_new
Project-URL: Issues, https://github.com/kushagrab21/Compiler_new/issues
Keywords: compiler,deterministic,proofs,hashes,rlang,bor
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: rlang-compiler>=0.2.1

# 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

```bash
pip install semantic-compiler-core
```

### Requirements

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

---

## Quick Start

### Minimal Example

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

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

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

### Running Tests

```bash
pytest tests/
```

### Building Distribution

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