invaria 0.1.0__tar.gz

invaria-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Local batch testing files
+batch_test.py
+batch_prompts.txt
+batch_result.txt
+
+# Environments & Package Management
+.venv
+venv/
+env/
+uv.lock
+
+# Python Cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / Packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE / OS 
+.vscode/
+.idea/
+.DS_Store
+
+.gitignore

invaria-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sgindeed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

invaria-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: invaria
+Version: 0.1.0
+Summary: Invaria — Universal LLM Context Compiler
+Project-URL: Homepage, https://github.com/sgindeed/invaria
+Project-URL: Repository, https://github.com/sgindeed/invaria
+Author-email: Supratim Ghosh <sgindeed234@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
+Provides-Extra: cli
+Requires-Dist: typer>=0.9.0; extra == 'cli'
+Provides-Extra: google
+Requires-Dist: google-genai>=0.3.0; extra == 'google'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.0.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Invaria — Universal LLM Context Compiler
+
+> **Compress less. Preserve more. Prove everything.**
+
+[![PyPI version](https://img.shields.io/pypi/v/invaria.svg)](https://pypi.org/project/invaria/)
+[![Python versions](https://img.shields.io/pypi/pyversions/invaria.svg)](https://pypi.org/project/invaria/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Invaria** is a deterministic, rule-based context compiler for Large Language Models. 
+
+Instead of blindly dropping tokens based on probabilistic attention scores (which often leads to hallucinated numbers, broken URLs, or lost named entities), Invaria treats your prompt as source code. It compiles the context into an intermediate representation (IR), generates compression candidates, **verifies** that strict preservation contracts are met, and emits the cheapest safe representation.
+
+---
+
+## Why Invaria?
+
+Most prompt compressors use smaller ML models to guess which words are "unimportant." This is dangerous for enterprise use cases where missing a "NOT", dropping a crucial ID, or altering a currency amount is catastrophic.
+
+Invaria introduces a **Verification Engine**. It mathematically guarantees that:
+*   ✅ **Numerical Invariants** (e.g., `$5000`, `99%`, `0.001`) are preserved.
+*   ✅ **Lexical Entities** (Proper nouns, CamelCase, Acronyms) are untouched.
+*   ✅ **Structured Identifiers** (URLs, Email addresses, API Keys, UUIDs) are safely retained.
+*   ✅ **Formatting** (Markdown tables, JSON structures, code blocks) remains syntactically valid.
+
+If a compressed candidate drops a required invariant, Invaria rejects it.
+
+---
+
+## Installation
+
+Install via pip. Invaria `v0.1.0` is extremely lightweight and relies primarily on `pydantic`.
+
+```bash
+pip install invaria
+```
+
+*Note: Optional dependencies for ML-based semantic compression (`openai`, `anthropic`, `google`) will be utilized in upcoming releases.*
+
+---
+
+## Python API Quickstart
+
+Invaria is designed to be easily integrated into your existing LLM pipelines, RAG systems, or agent frameworks.
+
+```python
+from invaria import Invaria
+
+# Initialize the compiler
+compiler = Invaria(mode="invariant")
+
+text = """
+User Alice transferred $5,000 to Bob on Monday... 
+Please do not delete the backup files!!! They are stored in Amazon S3.
+"""
+
+# Compress the context
+result = compiler.compress(text)
+
+# The compressed text
+print(result.text)
+# Output: "User Alice transferred $5,000 to Bob on Monday. Please do not delete the backup files! They are stored in Amazon S3."
+
+# Access detailed metrics
+print(f"Original Tokens:   {result.original_tokens}")
+print(f"Compressed Tokens: {result.compressed_tokens}")
+print(f"Token Reduction:   {result.token_reduction}")
+print(f"Compression Ratio: {result.compression_ratio:.2f}x")
+
+# Cryptographic proof of preservation
+print(f"Verified Safe:     {result.proof.verified}")
+print(f"Preserved Entities:{result.proof.preserved}")
+```
+
+### Inspecting Extracted Invariants
+
+You can also use Invaria just to parse and inspect the semantic constraints within a prompt without compressing it:
+
+```python
+ir = compiler.compile("Contact Support at help@example.com if Stripe webhooks fail.")
+
+for node_id, node in ir.nodes.items():
+    print(f"Type: {node.type} | Value: {node.value}")
+# Type: entity | Value: Contact
+# Type: entity | Value: Support
+# Type: entity | Value: help@example.com
+# Type: entity | Value: Stripe
+```
+
+---
+
+## CLI Usage
+
+Invaria comes with a built-in Command Line Interface for quickly compressing files or verifying external compressions in your CI/CD pipelines.
+
+### Compress a File
+```bash
+invaria compress prompt.txt --mode invariant
+```
+*Outputs the compression metrics, the cryptographic proof status, and the compressed text.*
+
+### Verify a Compression
+If you have an original context and a compressed version, Invaria can verify if the compressed version safely retained all necessary invariants from the original:
+```bash
+invaria verify original.txt compressed.txt
+```
+*Outputs `Verification Passed: True` or `False`.*
+
+---
+
+## Compiler Architecture
+
+Invaria operates similarly to a traditional programming language compiler:
+
+```mermaid
+graph LR
+    A[Text Input] --> B(COMPILE)
+    B -->|Semantic IR| C(OPTIMIZE)
+    C -->|Generate Candidates| D(VERIFY)
+    D -->|Check Constraints| E(EMIT)
+    E --> F[Verified Compressed Text]
+```
+
+1.  **Compile (Extract Invariants):** Scans the text to build a `SemanticGraph` (IR) identifying all Entities, Numerical Invariants, Dates, and Instructions.
+2.  **Optimize (Generate Candidates):** Applies active compressors (like `LexicalCompressor` for whitespace/punctuation normalization).
+3.  **Verify (Preservation Contract):** The `VerificationEngine` checks the candidate string against the Semantic IR to ensure zero critical tokens were lost or mutated.
+4.  **Emit:** Computes SHA-256 hashes for the proof, calculates token reductions, and returns a `CompressionResult`.
+
+---
+
+## Roadmap
+
+*   **v0.1.x (Current):** Deterministic Lexical Compression, Entity/Numerical Invariant Extraction, Core Verification Engine, CLI.
+*   **v0.2.x:** Syntactic Compression (safe removal of filler phrases, stop words) and Tiktoken integration for exact token pricing.
+*   **v0.3.x:** Abstractive Semantic Compression using LLM providers (`openai`, `anthropic`, `google`) backed by Invaria's deterministic `VerificationEngine` to prevent LLM hallucinations during summarization.
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2026 Supratim Ghosh & Invaria Contributors.

invaria-0.1.0/README.md

@@ -0,0 +1,142 @@
+# Invaria — Universal LLM Context Compiler
+
+> **Compress less. Preserve more. Prove everything.**
+
+[![PyPI version](https://img.shields.io/pypi/v/invaria.svg)](https://pypi.org/project/invaria/)
+[![Python versions](https://img.shields.io/pypi/pyversions/invaria.svg)](https://pypi.org/project/invaria/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Invaria** is a deterministic, rule-based context compiler for Large Language Models. 
+
+Instead of blindly dropping tokens based on probabilistic attention scores (which often leads to hallucinated numbers, broken URLs, or lost named entities), Invaria treats your prompt as source code. It compiles the context into an intermediate representation (IR), generates compression candidates, **verifies** that strict preservation contracts are met, and emits the cheapest safe representation.
+
+---
+
+## Why Invaria?
+
+Most prompt compressors use smaller ML models to guess which words are "unimportant." This is dangerous for enterprise use cases where missing a "NOT", dropping a crucial ID, or altering a currency amount is catastrophic.
+
+Invaria introduces a **Verification Engine**. It mathematically guarantees that:
+*   ✅ **Numerical Invariants** (e.g., `$5000`, `99%`, `0.001`) are preserved.
+*   ✅ **Lexical Entities** (Proper nouns, CamelCase, Acronyms) are untouched.
+*   ✅ **Structured Identifiers** (URLs, Email addresses, API Keys, UUIDs) are safely retained.
+*   ✅ **Formatting** (Markdown tables, JSON structures, code blocks) remains syntactically valid.
+
+If a compressed candidate drops a required invariant, Invaria rejects it.
+
+---
+
+## Installation
+
+Install via pip. Invaria `v0.1.0` is extremely lightweight and relies primarily on `pydantic`.
+
+```bash
+pip install invaria
+```
+
+*Note: Optional dependencies for ML-based semantic compression (`openai`, `anthropic`, `google`) will be utilized in upcoming releases.*
+
+---
+
+## Python API Quickstart
+
+Invaria is designed to be easily integrated into your existing LLM pipelines, RAG systems, or agent frameworks.
+
+```python
+from invaria import Invaria
+
+# Initialize the compiler
+compiler = Invaria(mode="invariant")
+
+text = """
+User Alice transferred $5,000 to Bob on Monday... 
+Please do not delete the backup files!!! They are stored in Amazon S3.
+"""
+
+# Compress the context
+result = compiler.compress(text)
+
+# The compressed text
+print(result.text)
+# Output: "User Alice transferred $5,000 to Bob on Monday. Please do not delete the backup files! They are stored in Amazon S3."
+
+# Access detailed metrics
+print(f"Original Tokens:   {result.original_tokens}")
+print(f"Compressed Tokens: {result.compressed_tokens}")
+print(f"Token Reduction:   {result.token_reduction}")
+print(f"Compression Ratio: {result.compression_ratio:.2f}x")
+
+# Cryptographic proof of preservation
+print(f"Verified Safe:     {result.proof.verified}")
+print(f"Preserved Entities:{result.proof.preserved}")
+```
+
+### Inspecting Extracted Invariants
+
+You can also use Invaria just to parse and inspect the semantic constraints within a prompt without compressing it:
+
+```python
+ir = compiler.compile("Contact Support at help@example.com if Stripe webhooks fail.")
+
+for node_id, node in ir.nodes.items():
+    print(f"Type: {node.type} | Value: {node.value}")
+# Type: entity | Value: Contact
+# Type: entity | Value: Support
+# Type: entity | Value: help@example.com
+# Type: entity | Value: Stripe
+```
+
+---
+
+## CLI Usage
+
+Invaria comes with a built-in Command Line Interface for quickly compressing files or verifying external compressions in your CI/CD pipelines.
+
+### Compress a File
+```bash
+invaria compress prompt.txt --mode invariant
+```
+*Outputs the compression metrics, the cryptographic proof status, and the compressed text.*
+
+### Verify a Compression
+If you have an original context and a compressed version, Invaria can verify if the compressed version safely retained all necessary invariants from the original:
+```bash
+invaria verify original.txt compressed.txt
+```
+*Outputs `Verification Passed: True` or `False`.*
+
+---
+
+## Compiler Architecture
+
+Invaria operates similarly to a traditional programming language compiler:
+
+```mermaid
+graph LR
+    A[Text Input] --> B(COMPILE)
+    B -->|Semantic IR| C(OPTIMIZE)
+    C -->|Generate Candidates| D(VERIFY)
+    D -->|Check Constraints| E(EMIT)
+    E --> F[Verified Compressed Text]
+```
+
+1.  **Compile (Extract Invariants):** Scans the text to build a `SemanticGraph` (IR) identifying all Entities, Numerical Invariants, Dates, and Instructions.
+2.  **Optimize (Generate Candidates):** Applies active compressors (like `LexicalCompressor` for whitespace/punctuation normalization).
+3.  **Verify (Preservation Contract):** The `VerificationEngine` checks the candidate string against the Semantic IR to ensure zero critical tokens were lost or mutated.
+4.  **Emit:** Computes SHA-256 hashes for the proof, calculates token reductions, and returns a `CompressionResult`.
+
+---
+
+## Roadmap
+
+*   **v0.1.x (Current):** Deterministic Lexical Compression, Entity/Numerical Invariant Extraction, Core Verification Engine, CLI.
+*   **v0.2.x:** Syntactic Compression (safe removal of filler phrases, stop words) and Tiktoken integration for exact token pricing.
+*   **v0.3.x:** Abstractive Semantic Compression using LLM providers (`openai`, `anthropic`, `google`) backed by Invaria's deterministic `VerificationEngine` to prevent LLM hallucinations during summarization.
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2026 Supratim Ghosh & Invaria Contributors.

invaria-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "invaria"
+version = "0.1.0"
+description = "Invaria — Universal LLM Context Compiler"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Supratim Ghosh", email = "sgindeed234@gmail.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "pydantic>=2.0.0"
+]
+
+[project.optional-dependencies]
+openai = [
+    "openai>=1.0.0"
+]
+anthropic = [
+    "anthropic>=0.18.0"
+]
+google = [
+    "google-genai>=0.3.0"
+]
+cli = [
+    "typer>=0.9.0"
+]
+test = [
+    "pytest>=7.0.0",
+    "hypothesis>=6.0.0",
+    "pytest-asyncio>=0.21.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/sgindeed/invaria"
+Repository = "https://github.com/sgindeed/invaria"
+
+[project.scripts]
+invaria = "invaria.cli.main:main"
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q"
+testpaths = ["tests"]
+asyncio_mode = "strict"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/invaria"]

invaria-0.1.0/src/invaria/__init__.py

@@ -0,0 +1,4 @@
+from .api import Invaria
+
+__version__ = "0.1.0"
+__all__ = ["Invaria"]

invaria-0.1.0/src/invaria/api.py

@@ -0,0 +1,31 @@
+from typing import Optional
+from .config import InvariaConfig
+from .compiler.pipeline import CompilerPipeline, CompressionResult
+from .ir.models import SemanticGraph
+
+class Invaria:
+    def __init__(self, **kwargs):
+        self.config = InvariaConfig(**kwargs)
+        self.pipeline = CompilerPipeline(self.config)
+
+    def compress(self, text: str, **kwargs) -> CompressionResult:
+        # Override config optionally for this run
+        if kwargs:
+            local_config = self.config.model_copy(update=kwargs)
+            local_pipeline = CompilerPipeline(local_config)
+            return local_pipeline.compress(text)
+        return self.pipeline.compress(text)
+
+    def compile(self, text: str) -> SemanticGraph:
+        return self.pipeline.compile(text)
+
+    def verify(self, original: str, compressed: str) -> bool:
+        ir = self.pipeline.compile(original)
+        report = self.pipeline.verifier.verify(ir, compressed)
+        return report.passed
+
+    def inspect(self, text: str) -> SemanticGraph:
+        return self.pipeline.compile(text)
+
+    def benchmark(self, text: str) -> None:
+        raise NotImplementedError("Benchmark framework is not yet initialized.")

invaria-0.1.0/src/invaria/cli/main.py

@@ -0,0 +1,49 @@
+import argparse
+import sys
+from ..api import Invaria
+
+def main():
+    parser = argparse.ArgumentParser(description="Invaria — Universal LLM Context Compiler")
+    subparsers = parser.add_subparsers(dest="command")
+
+    compress_parser = subparsers.add_parser("compress", help="Compress a context")
+    compress_parser.add_argument("input_file", help="Input file path")
+    compress_parser.add_argument("--mode", default="invariant", help="Compression mode")
+
+    verify_parser = subparsers.add_parser("verify", help="Verify a compressed context")
+    verify_parser.add_argument("original", help="Original context file")
+    verify_parser.add_argument("compressed", help="Compressed context file")
+
+    args = parser.parse_args()
+    
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+        
+    compiler = Invaria()
+
+    if args.command == "compress":
+        with open(args.input_file, 'r', encoding='utf-8') as f:
+            text = f.read()
+        
+        result = compiler.compress(text, mode=args.mode)
+        
+        print(f"Original tokens (approx): {result.original_tokens}")
+        print(f"Compressed tokens (approx): {result.compressed_tokens}")
+        print(f"Reduction: {result.token_reduction}")
+        print(f"Ratio: {result.compression_ratio:.2f}")
+        print(f"Verified: {result.proof.verified}")
+        print("\n--- COMPRESSED OUTPUT ---")
+        print(result.text)
+
+    elif args.command == "verify":
+        with open(args.original, 'r', encoding='utf-8') as f:
+            orig_text = f.read()
+        with open(args.compressed, 'r', encoding='utf-8') as f:
+            comp_text = f.read()
+            
+        is_valid = compiler.verify(orig_text, comp_text)
+        print(f"Verification Passed: {is_valid}")
+
+if __name__ == "__main__":
+    main()

invaria-0.1.0/src/invaria/compiler/pipeline.py

@@ -0,0 +1,244 @@
+import hashlib
+import json
+import re
+from typing import List, Dict, Any
+from pydantic import BaseModel
+
+from ..config import InvariaConfig
+from ..ir.models import (
+    SemanticGraph,
+    Entity,
+    NumericalInvariant,
+    SourceSpan,
+)
+from ..compressors.lexical import LexicalCompressor
+from ..verification.verifier import VerificationEngine
+from ..verification.contract import PreservationContract
+from ..verification.report import CompressionProof
+from ..optimizer.search import Optimizer
+
+
+class CompressionResult(BaseModel):
+    text: str
+    original_tokens: int
+    compressed_tokens: int
+    token_reduction: int
+    compression_ratio: float
+    mode: str
+    representation: str
+    proof: CompressionProof
+    invariants: List[Any]
+    warnings: List[str]
+    metadata: Dict[str, Any]
+
+
+class CompilerPipeline:
+    # Matches words, numbers with currency/units/decimals, times, emails, and identifiers
+    _TOKEN_PATTERN = re.compile(
+        r"[A-Za-z0-9_$%+-]+(?:[@.:/-][A-Za-z0-9_$%+-]+)*"
+    )
+
+    def __init__(self, config: InvariaConfig):
+        self.config = config
+        self.compressors = [LexicalCompressor()]
+        self.contract = PreservationContract(strictness=config.mode)
+        self.verifier = VerificationEngine(self.contract)
+        self.optimizer = Optimizer(config)
+        self._compressor_map = {c.name: c for c in self.compressors}
+
+    @staticmethod
+    def _hash_text(text: str) -> str:
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
+
+    @staticmethod
+    def _hash_ir(ir: SemanticGraph) -> str:
+        payload = json.dumps(
+            {k: v.model_dump() for k, v in sorted(ir.nodes.items())},
+            sort_keys=True,
+            default=str,
+        )
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+    def extract_invariants(self, text: str) -> SemanticGraph:
+        graph = SemanticGraph()
+        # Only treat short ALL-CAPS words as acronyms if the text itself isn't shouting in ALL CAPS
+        text_has_lowercase = any(c.islower() for c in text)
+
+        for idx, match in enumerate(self._TOKEN_PATTERN.finditer(text)):
+            raw_token = match.group(0)
+            clean_token = raw_token.strip(".,!?:;\"'()[]{}-")
+            if not clean_token:
+                continue
+
+            start, end = match.span()
+            span = SourceSpan(start_char=start, end_char=end, text=raw_token)
+
+            has_digit = any(ch.isdigit() for ch in clean_token)
+            has_alpha = any(ch.isalpha() for ch in clean_token)
+
+            # 1. Numerical / Quantitative Invariants (pure numbers, currency, percentages, versions, times)
+            if has_digit and not has_alpha:
+                unit = None
+                if clean_token.startswith(("$", "€", "£", "₹")):
+                    unit = clean_token[0]
+                elif clean_token.endswith("%"):
+                    unit = "%"
+                node_id = f"num_{idx}"
+                graph.nodes[node_id] = NumericalInvariant(
+                    id=node_id,
+                    value=clean_token,
+                    normalized_value=clean_token,
+                    unit=unit,
+                    source_span=span,
+                )
+
+            # 2. Mixed Alphanumeric Identifiers & Quantities (e.g., S3, AI302, 500mg, 15th)
+            elif has_digit and has_alpha:
+                if clean_token[0].isdigit():
+                    node_id = f"num_{idx}"
+                    graph.nodes[node_id] = NumericalInvariant(
+                        id=node_id,
+                        value=clean_token,
+                        normalized_value=clean_token,
+                        source_span=span,
+                    )
+                else:
+                    node_id = f"ent_{idx}"
+                    graph.nodes[node_id] = Entity(
+                        id=node_id,
+                        value=clean_token,
+                        normalized_value=clean_token,
+                        source_span=span,
+                    )
+
+            # 3. Structured Identifiers (e.g., emails or domain-like tokens containing '@')
+            elif "@" in clean_token:
+                node_id = f"ent_{idx}"
+                graph.nodes[node_id] = Entity(
+                    id=node_id,
+                    value=clean_token,
+                    normalized_value=clean_token,
+                    source_span=span,
+                )
+
+            # 4. Lexical Entities: Proper Nouns, CamelCase/PascalCase, and Acronyms
+            elif len(clean_token) >= 2:
+                is_camel_or_pascal = (
+                    any(c.isupper() for c in clean_token[1:])
+                    and any(c.islower() for c in clean_token)
+                )
+                is_capitalized_word = (
+                    clean_token[0].isupper()
+                    and clean_token[1:].islower()
+                    and len(clean_token) > 2
+                )
+                is_acronym = (
+                    text_has_lowercase
+                    and clean_token.isupper()
+                    and 2 <= len(clean_token) <= 5
+                )
+
+                if is_camel_or_pascal or is_capitalized_word or is_acronym:
+                    node_id = f"ent_{idx}"
+                    graph.nodes[node_id] = Entity(
+                        id=node_id,
+                        value=clean_token,
+                        normalized_value=clean_token.lower(),
+                        source_span=span,
+                    )
+
+        return graph
+
+    def compile(self, text: str) -> SemanticGraph:
+        return self.extract_invariants(text)
+
+    def compress(self, text: str) -> CompressionResult:
+        original_tokens = len(text)
+        orig_hash = self._hash_text(text)
+
+        # 1. COMPILE
+        ir = self.compile(text)
+        inv_hash = self._hash_ir(ir)
+
+        # 2. GENERATE CANDIDATES
+        all_candidates = []
+        for comp in self.compressors:
+            if comp.can_handle(text, ir, self.config):
+                candidates = comp.generate_candidates(text, ir, self.config)
+                for cand in candidates:
+                    all_candidates.append((comp.name, cand))
+
+        # 3. VERIFY
+        valid_candidates = []
+        costs = []
+        proofs = []
+
+        for comp_name, cand in all_candidates:
+            report = self.verifier.verify(ir, cand)
+            if report.passed:
+                valid_candidates.append(cand)
+                # 4. MEASURE COST using the specific compressor that generated the candidate
+                comp_instance = self._compressor_map[comp_name]
+                cost = comp_instance.estimate_cost(cand, self.config)
+                costs.append(cost)
+
+                proof = CompressionProof(
+                    original_hash=orig_hash,
+                    invariant_hash=inv_hash,
+                    candidate_hash=self._hash_text(cand),
+                    verified=True,
+                    exact_reconstruction=(cand == text),
+                    preservation_contract=self.config.mode,
+                    preserved=len(report.preserved_invariants),
+                    changed=len(report.changed_invariants),
+                    warnings=report.warnings,
+                    compressor_chain=[comp_name],
+                )
+                proofs.append(proof)
+
+        # FAIL-SAFE
+        if not valid_candidates:
+            return CompressionResult(
+                text=text,
+                original_tokens=original_tokens,
+                compressed_tokens=original_tokens,
+                token_reduction=0,
+                compression_ratio=1.0,
+                mode=self.config.mode,
+                representation="original",
+                proof=CompressionProof(
+                    original_hash=orig_hash,
+                    invariant_hash=inv_hash,
+                    candidate_hash=orig_hash,
+                    verified=True,
+                    exact_reconstruction=True,
+                    preservation_contract=self.config.mode,
+                    preserved=len(ir.nodes),
+                    changed=0,
+                ),
+                invariants=list(ir.nodes.values()),
+                warnings=["Fallback to original text"],
+                metadata={},
+            )
+
+        # 5. OPTIMIZE & SELECT
+        best_cand = self.optimizer.select_best(valid_candidates, costs)
+        best_idx = valid_candidates.index(best_cand)
+        best_proof = proofs[best_idx]
+
+        comp_tokens = len(best_cand)
+
+        # 6. RETURN
+        return CompressionResult(
+            text=best_cand,
+            original_tokens=original_tokens,
+            compressed_tokens=comp_tokens,
+            token_reduction=original_tokens - comp_tokens,
+            compression_ratio=original_tokens / comp_tokens if comp_tokens > 0 else 0.0,
+            mode=self.config.mode,
+            representation=best_proof.compressor_chain[0],
+            proof=best_proof,
+            invariants=list(ir.nodes.values()),
+            warnings=best_proof.warnings,
+            metadata={},
+        )

invaria-0.1.0/src/invaria/compressors/base.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+from typing import Any, List, Optional
+from ..config import InvariaConfig
+from ..ir.models import SemanticGraph
+
+class Compressor(ABC):
+    name: str
+
+    @abstractmethod
+    def can_handle(self, context: str, ir: SemanticGraph, config: InvariaConfig) -> bool:
+        pass
+
+    @abstractmethod
+    def generate_candidates(self, context: str, ir: SemanticGraph, config: InvariaConfig) -> List[str]:
+        pass
+
+    @abstractmethod
+    def estimate_cost(self, candidate: str, config: InvariaConfig) -> float:
+        pass

invaria-0.1.0/src/invaria/compressors/lexical.py

@@ -0,0 +1,31 @@
+import re
+from typing import List
+from .base import Compressor
+from ..config import InvariaConfig
+from ..ir.models import SemanticGraph
+
+class LexicalCompressor(Compressor):
+    name: str = "lexical"
+
+    def can_handle(self, context: str, ir: SemanticGraph, config: InvariaConfig) -> bool:
+        return True
+
+    def generate_candidates(self, context: str, ir: SemanticGraph, config: InvariaConfig) -> List[str]:
+        # Basic deterministic lexical transformations
+        
+        # 1. Whitespace normalization
+        normalized = re.sub(r'\s+', ' ', context).strip()
+        
+        # 2. Duplicate punctuation cleanup
+        cleaned = re.sub(r'([.?!,])\1+', r'\1', normalized)
+        
+        candidates = [normalized]
+        if cleaned != normalized:
+            candidates.append(cleaned)
+            
+        return candidates
+
+    def estimate_cost(self, candidate: str, config: InvariaConfig) -> float:
+        # Simple heuristic: length of string as a proxy for token cost
+        # In later phases, use actual tokenizer
+        return float(len(candidate))

invaria-0.1.0/src/invaria/config.py

@@ -0,0 +1,13 @@
+from typing import Optional, Literal
+from pydantic import BaseModel, Field
+
+class InvariaConfig(BaseModel):
+    mode: Literal["semantic", "invariant", "reversible"] = "invariant"
+    provider: Optional[str] = None
+    model: Optional[str] = None
+    tokenizer: Optional[str] = None
+    verify: bool = True
+    logging_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
+    
+    # Optimizer settings
+    target_tokens: Optional[int] = None

invaria-0.1.0/src/invaria/exceptions.py

@@ -0,0 +1,47 @@
+class InvariaError(Exception):
+    """Base exception for all Invaria errors."""
+    pass
+
+class ParsingError(InvariaError):
+    """Raised when parsing context fails."""
+    pass
+
+class UnsupportedContentError(InvariaError):
+    """Raised when content type is not supported."""
+    pass
+
+class CompressionError(InvariaError):
+    """Raised when compression process fails."""
+    pass
+
+class VerificationError(InvariaError):
+    """Raised when a candidate fails verification checks."""
+    pass
+
+class InvariantViolation(VerificationError):
+    """Raised when a required invariant is violated."""
+    pass
+
+class ReconstructionError(VerificationError):
+    """Raised when exact reversible reconstruction fails."""
+    pass
+
+class ConfigurationError(InvariaError):
+    """Raised when configuration is invalid."""
+    pass
+
+class ProviderError(InvariaError):
+    """Raised when interacting with an LLM provider fails."""
+    pass
+
+class TokenizerError(InvariaError):
+    """Raised when tokenization fails."""
+    pass
+
+class RenderingError(InvariaError):
+    """Raised when rendering a candidate fails."""
+    pass
+
+class OptimizationError(InvariaError):
+    """Raised when the optimization engine fails to find a valid representation."""
+    pass

invaria-0.1.0/src/invaria/ir/models.py

@@ -0,0 +1,53 @@
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+class SourceSpan(BaseModel):
+    start_char: int
+    end_char: int
+    text: str
+
+class SemanticNode(BaseModel):
+    id: str
+    type: str
+    value: Any
+    normalized_value: Optional[Any] = None
+    source_span: Optional[SourceSpan] = None
+    confidence: float = 1.0
+    provenance: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+class Entity(SemanticNode):
+    type: str = "entity"
+
+class Fact(SemanticNode):
+    type: str = "fact"
+    subject: str
+    predicate: str
+    object: str
+
+class Constraint(SemanticNode):
+    type: str = "constraint"
+    polarity: str = "positive" # "positive" or "negative"
+
+class NumericalInvariant(SemanticNode):
+    type: str = "number"
+    unit: Optional[str] = None
+
+class TemporalInvariant(SemanticNode):
+    type: str = "temporal"
+    relation: str = "at" # "before", "after", "at"
+
+class Instruction(SemanticNode):
+    type: str = "instruction"
+    modality: str = "must" # "must", "should", "may", etc.
+
+class GraphEdge(BaseModel):
+    source_id: str
+    target_id: str
+    relation: str
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+class SemanticGraph(BaseModel):
+    nodes: Dict[str, SemanticNode] = Field(default_factory=dict)
+    edges: List[GraphEdge] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)

invaria-0.1.0/src/invaria/optimizer/search.py

@@ -0,0 +1,14 @@
+from typing import List, Tuple
+from ..config import InvariaConfig
+
+class Optimizer:
+    def __init__(self, config: InvariaConfig):
+        self.config = config
+
+    def select_best(self, valid_candidates: List[str], costs: List[float]) -> str:
+        if not valid_candidates:
+            raise ValueError("No valid candidates provided to the optimizer.")
+        
+        # Simple greedy search: select the one with the lowest cost
+        best_idx = costs.index(min(costs))
+        return valid_candidates[best_idx]

invaria-0.1.0/src/invaria/verification/contract.py

@@ -0,0 +1,14 @@
+from typing import List, Set
+from pydantic import BaseModel, Field
+
+class PreservationContract(BaseModel):
+    strictness: str = "strict"
+    required: Set[str] = Field(default_factory=lambda: {
+        "entities",
+        "facts",
+        "constraints",
+        "numbers",
+        "dates",
+        "instructions"
+    })
+    verification_level: str = "CRITICAL"

invaria-0.1.0/src/invaria/verification/report.py

@@ -0,0 +1,23 @@
+from typing import List, Any
+from pydantic import BaseModel, Field
+
+class VerificationReport(BaseModel):
+    passed: bool
+    critical_failures: List[str] = Field(default_factory=list)
+    warnings: List[str] = Field(default_factory=list)
+    preserved_invariants: List[Any] = Field(default_factory=list)
+    changed_invariants: List[Any] = Field(default_factory=list)
+    missing_invariants: List[Any] = Field(default_factory=list)
+    confidence: float = 1.0
+
+class CompressionProof(BaseModel):
+    original_hash: str
+    invariant_hash: str
+    candidate_hash: str
+    verified: bool
+    exact_reconstruction: bool
+    preservation_contract: str
+    preserved: int
+    changed: int
+    warnings: List[str] = Field(default_factory=list)
+    compressor_chain: List[str] = Field(default_factory=list)

invaria-0.1.0/src/invaria/verification/verifier.py

@@ -0,0 +1,40 @@
+import re
+from .report import VerificationReport
+from .contract import PreservationContract
+from ..ir.models import SemanticGraph
+
+
+class VerificationEngine:
+    def __init__(self, contract: PreservationContract):
+        self.contract = contract
+
+    @staticmethod
+    def _contains_exact_token(text: str, token: str) -> bool:
+        escaped = re.escape(token)
+        # Ensure alphanumeric boundaries are respected so '15' doesn't match '1500'
+        prefix = r"(?<![A-Za-z0-9_])" if token[0].isalnum() else ""
+        suffix = r"(?![A-Za-z0-9_])" if token[-1].isalnum() else ""
+        pattern = f"{prefix}{escaped}{suffix}"
+        return re.search(pattern, text) is not None
+
+    def verify(self, original_ir: SemanticGraph, candidate_text: str) -> VerificationReport:
+        failures = []
+        preserved = []
+        missing = []
+
+        for node_id, node in original_ir.nodes.items():
+            val_str = str(node.value)
+            if self._contains_exact_token(candidate_text, val_str):
+                preserved.append(node)
+            else:
+                failures.append(f"Missing invariant ({node.type}): {val_str}")
+                missing.append(node)
+
+        passed = len(failures) == 0
+
+        return VerificationReport(
+            passed=passed,
+            critical_failures=failures,
+            preserved_invariants=preserved,
+            missing_invariants=missing,
+        )

invaria-0.1.0/tests/unit/test_api.py

@@ -0,0 +1,22 @@
+from invaria import Invaria
+
+def test_basic_compression():
+    compiler = Invaria(mode="invariant")
+    text = "This   is  a test.    This is only a test."
+    
+    result = compiler.compress(text)
+    
+    assert result.proof.verified is True
+    # The lexical compressor should have cleaned up spaces
+    assert result.text == "This is a test. This is only a test."
+    assert result.compressed_tokens < result.original_tokens
+
+def test_compile_api():
+    compiler = Invaria()
+    text = "PostgreSQL is a great database."
+    ir = compiler.compile(text)
+    
+    # Should have extracted some naive entities (e.g., PostgreSQL)
+    assert len(ir.nodes) > 0
+    found_pg = any(node.value == "PostgreSQL" for node in ir.nodes.values())
+    assert found_pg is True