ctxfw 3.5.0__py3-none-any.whl

ctxfw/__init__.py

@@ -0,0 +1,42 @@
+"""
+ctxfw — Sovereign Context Firewall & Token Optimization Engine (v3.4.0)
+Hermetic Toolchain implementation adhering to Google style and POSIX/XDG standards.
+"""
+from __future__ import annotations
+
+from ctxfw.core.contracts import (
+    OptimizationRequestDTO,
+    OptimizationResultDTO,
+    PruningDepth,
+    SupportedLanguage,
+)
+from ctxfw.core.polyglot import TreeSitterContextPruner
+from ctxfw.core.pruner import DeterministicContextPruner, _MethodBodyStripper
+from ctxfw.core.topological import (
+    ContextFirewallEngine,
+    ProjectDependencyGraph,
+    StaticImportExtractor,
+    TopologicalContextBundleDTO,
+)
+from ctxfw.cli import handle_init_command
+from ctxfw.storage.cache import LocalSemanticCache, get_canonical_cache_path
+
+__version__ = "3.5.0"
+
+__all__ = [
+    "__version__",
+    "PruningDepth",
+    "SupportedLanguage",
+    "OptimizationRequestDTO",
+    "OptimizationResultDTO",
+    "DeterministicContextPruner",
+    "_MethodBodyStripper",
+    "TreeSitterContextPruner",
+    "StaticImportExtractor",
+    "ProjectDependencyGraph",
+    "TopologicalContextBundleDTO",
+    "ContextFirewallEngine",
+    "LocalSemanticCache",
+    "get_canonical_cache_path",
+    "handle_init_command",
+]

ctxfw/__main__.py

@@ -0,0 +1,7 @@
+"""
+src/ctxfw/__main__.py — Entrypoint for `python -m ctxfw`
+"""
+from ctxfw.cli import main
+
+if __name__ == "__main__":
+    main()

ctxfw/auditor.py

@@ -0,0 +1,165 @@
+"""
+src/ctxfw/auditor.py — FinOps Ledger & Token Economics Auditor (v3.4.0)
+Calculates token reduction metrics, USD cost avoidance, and cache bypass efficiency
+in a 100% air-gapped, zero-cloud verification loop.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+from ctxfw.core.contracts import OptimizationResultDTO
+from ctxfw.core.pruner import DeterministicContextPruner
+from ctxfw.core.topological import TopologicalContextBundleDTO
+from ctxfw.storage.cache import get_canonical_cache_path
+
+
+class FinOpsReportDTO(BaseModel):
+    """Contrato inmutable de auditoría financiera y métricas de tokens."""
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    total_tokens_evaluated: int = Field(..., ge=0, description="Volumen total de tokens evaluados en código original")
+    tokens_saved_cold: int = Field(..., ge=0, description="Tokens ahorrados mediante slicing sintáctico AST")
+    tokens_saved_cache_bypass: int = Field(..., ge=0, description="Tokens 100% eludidos mediante hits de caché cálida")
+    net_tokens_saved: int = Field(..., ge=0, description="Total neto de tokens ahorrados")
+    estimated_usd_savings: float = Field(..., ge=0.0, description="Ahorro financiero proyectado en USD")
+    cache_hit_ratio: float = Field(..., ge=0.0, le=100.0, description="Tasa porcentual de aciertos de caché")
+    air_gapped_certified: bool = Field(default=True, description="Certificación de ejecución 100% local sin red")
+    timestamp: str = Field(..., description="Marca temporal UTC de la auditoría en formato ISO 8601")
+
+
+class FinOpsAuditor:
+    """Motor de cálculo financiero y auditoría de tokens."""
+
+    DEFAULT_PRICE_PER_MILLION: float = 3.0  # Base USD por 1M de tokens (tier estándar frontier LLM)
+
+    @classmethod
+    def audit_bundle(
+        cls,
+        bundle: TopologicalContextBundleDTO,
+        price_per_million_tokens: float = DEFAULT_PRICE_PER_MILLION,
+    ) -> FinOpsReportDTO:
+        """Calculates token savings and monetary return on an active context bundle."""
+        total_tokens = 0
+        saved_cold = 0
+        saved_bypass = 0
+        hits = 0
+        total_entries = len(bundle.entries)
+
+        for res in bundle.entries.values():
+            orig_t = DeterministicContextPruner.estimate_tokens(res.original_chars)
+            total_tokens += orig_t
+
+            if res.cache_hit:
+                hits += 1
+                # In warm cache hits, 100% of the token context is bypassed
+                saved_bypass += orig_t
+            else:
+                saved_cold += res.estimated_tokens_saved
+
+        net_saved = saved_cold + saved_bypass
+        hit_ratio = round((hits / max(1, total_entries)) * 100.0, 2)
+        usd_savings = round((net_saved / 1_000_000.0) * price_per_million_tokens, 6)
+
+        return FinOpsReportDTO(
+            total_tokens_evaluated=total_tokens,
+            tokens_saved_cold=saved_cold,
+            tokens_saved_cache_bypass=saved_bypass,
+            net_tokens_saved=net_saved,
+            estimated_usd_savings=usd_savings,
+            cache_hit_ratio=hit_ratio,
+            air_gapped_certified=True,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+
+    @classmethod
+    def audit_cache(
+        cls,
+        db_path: Optional[str | Path] = None,
+        price_per_million_tokens: float = DEFAULT_PRICE_PER_MILLION,
+    ) -> FinOpsReportDTO:
+        """Queries persistent SQLite WAL tokens_cache and computes aggregate financial return."""
+        actual_path = Path(db_path) if db_path else get_canonical_cache_path()
+        if not actual_path.is_file():
+            return FinOpsReportDTO(
+                total_tokens_evaluated=0,
+                tokens_saved_cold=0,
+                tokens_saved_cache_bypass=0,
+                net_tokens_saved=0,
+                estimated_usd_savings=0.0,
+                cache_hit_ratio=0.0,
+                air_gapped_certified=True,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+
+        with sqlite3.connect(str(actual_path), timeout=5.0) as conn:
+            cur = conn.cursor()
+            cur.execute("""
+                SELECT 
+                    COUNT(*),
+                    COALESCE(SUM(original_chars), 0),
+                    COALESCE(SUM(pruned_chars), 0),
+                    COALESCE(SUM(estimated_tokens_saved), 0)
+                FROM tokens_cache;
+            """)
+            count, orig_chars, pruned_chars, saved_tokens = cur.fetchone()
+
+        total_tokens = DeterministicContextPruner.estimate_tokens(orig_chars)
+        net_saved = int(saved_tokens)
+        usd_savings = round((net_saved / 1_000_000.0) * price_per_million_tokens, 6)
+        hit_ratio = 100.0 if count > 0 else 0.0
+
+        return FinOpsReportDTO(
+            total_tokens_evaluated=total_tokens,
+            tokens_saved_cold=net_saved,
+            tokens_saved_cache_bypass=0,
+            net_tokens_saved=net_saved,
+            estimated_usd_savings=usd_savings,
+            cache_hit_ratio=hit_ratio,
+            air_gapped_certified=True,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+
+    @classmethod
+    def export_audit(
+        cls,
+        report: FinOpsReportDTO,
+        output_path: str = "tests/finops_audit.json",
+    ) -> None:
+        """Exports the FinOps report to a machine-readable JSON artifact."""
+        out = Path(output_path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        with open(out, "w", encoding="utf-8") as f:
+            f.write(report.model_dump_json(indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="ctxfw-audit — Token Economics & FinOps Auditor (v3.4.0)")
+    parser.add_argument("--db", type=str, default=None, help="Path to SQLite cache database (defaults to canonical XDG path)")
+    parser.add_argument("--price", type=float, default=3.0, help="Base USD price per 1M tokens")
+    parser.add_argument("--json", action="store_true", help="Print report as JSON to stdout")
+    args = parser.parse_args()
+
+    report = FinOpsAuditor.audit_cache(db_path=args.db, price_per_million_tokens=args.price)
+    if args.json:
+        print(report.model_dump_json(indent=2))
+    else:
+        print("======================================================")
+        print("   CTXFW FINOPS LEDGER & AUDIT TELEMETRY              ")
+        print("======================================================")
+        print(f"Total Tokens Evaluated: {report.total_tokens_evaluated:,}")
+        print(f"Net Tokens Saved:       {report.net_tokens_saved:,}")
+        print(f"Estimated USD Savings:  ${report.estimated_usd_savings:.6f}")
+        print(f"Air-gapped Certified:   {report.air_gapped_certified}")
+        print(f"Timestamp:              {report.timestamp}")
+        print("======================================================")
+
+
+if __name__ == "__main__":
+    main()