cfa-kernel 0.1.1__tar.gz → 0.1.3__tar.gz

cfa_kernel-0.1.3/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: cfa-kernel
+Version: 0.1.3
+Summary: CFA — Governed execution for AI agents and data systems
+Project-URL: Homepage, https://marquesantero.github.io/cfa/
+Project-URL: Repository, https://github.com/marquesantero/cfa
+Project-URL: Documentation, https://marquesantero.github.io/cfa/docs/intro
+License: MIT
+License-File: LICENSE
+Keywords: ai,audit,compliance,data,governance,pipeline,policy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: mcp>=1.0; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.20; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: openai>=1.0; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# CFA v0.1.2
+
+[![CI](https://github.com/marquesantero/cfa/actions/workflows/ci.yml/badge.svg)](https://github.com/marquesantero/cfa/actions/workflows/ci.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Tests](https://img.shields.io/badge/tests-536%20passed-brightgreen)](https://github.com/marquesantero/cfa/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/cfa-kernel)](https://pypi.org/project/cfa-kernel/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Docs](https://img.shields.io/badge/docs-docusaurus-blue.svg)](https://marquesantero.github.io/cfa/)
+
+**Governed execution for AI agents and data systems.**
+
+Instead of asking _"which agent or skill should act?"_, CFA asks _"which state transition is being requested, under which constraints, and can it be executed safely?"_ and produces a cryptographically verifiable decision.
+
+## Quick Start
+
+```bash
+pip install cfa-kernel
+# or: pip install git+https://github.com/marquesantero/cfa.git
+cfa init
+cfa evaluate "Join NFe with Clientes and persist to Silver" --catalog .cfa/catalog.json
+```
+
+## What CFA does
+
+| Step | What happens |
+|------|-------------|
+| **Formalize** | Natural language or JSON → typed `StateSignature` contract |
+| **Govern** | Policy Engine evaluates PII, cost, schema, partition constraints |
+| **Generate** | Execution planner + deterministic code generation (PySpark, SQL, dbt) |
+| **Execute** | Pluggable sandbox with metrics collection + runtime validation |
+| **Validate** | State projection, SHA-256 audit trail, lifecycle indices |
+
+## Surfaces
+
+All interfaces are backend-agnostic. CFA evaluates a `StateSignature` contract — however it was produced.
+
+| Surface | For | Example |
+|---------|-----|---------|
+| `cfa` CLI | Everyone | `cfa policy check --signature sig.json` |
+| `cfa catalog` CLI | Data platform teams | `cfa catalog validate catalog.json` |
+| `cfa policy` CLI | Security/compliance | `cfa policy validate policies/prod.yaml` |
+| `cfa storage` CLI | Operations | `cfa storage stats --db cfa.db` |
+| `cfa lifecycle` CLI | Platform teams | `cfa lifecycle evaluate --db cfa.db` |
+| `cfa signature` CLI | External systems | `cfa signature validate request.json` |
+| `cfa.testing` | CI/CD | `evaluate("intent", catalog=catalog)` with pytest |
+| `cfa.runtime` | Production | `RuntimeGate` as decorator/context-manager |
+| `cfa.mcp` | AI agents | MCP server for any MCP-compatible client |
+| `cfa.adapters` | AI frameworks | LangGraph, OpenAI Agents, CrewAI, AutoGen, DSPy |
+
+## Architecture
+
+```text
+CLI / MCP / Adapter / API
+        │
+        ▼
+   ┌─ Formalize ──┐   NL / JSON / Tool call → typed StateSignature contract
+   ├─ Govern ──────┤   Policy check + REPLAN cycle (approve / replan / block)
+   ├─ Generate ────┤   Plan + code (PySpark / SQL / dbt) + static validation
+   ├─ Execute ─────┤   Pluggable sandbox + runtime validation
+   └─ Validate ────┘   State projection + SHA-256 audit + lifecycle indices
+                           │
+                           ▼
+            Decision JSON / Audit Trail / OTel / Prometheus
+```
+
+## Key Differentiators
+
+| Feature | CFA | Others |
+|---------|-----|--------|
+| SHA-256 audit trail (tamper-evident) | ✅ | ❌ |
+| State projection between executions | ✅ | ❌ |
+| Lifecycle indices (IFo/IFs/IFg/IDI) | ✅ | ❌ |
+| REPLAN with auto-interventions | ✅ | ❌ |
+| Backend-agnostic (PySpark, SQL, dbt) | ✅ | ❌ |
+| Artifact hashing (catalog + policy + signature) | ✅ | ❌ |
+| MCP protocol for AI agents | ✅ | ❌ |
+| SQLite storage with retention management | ✅ | ❌ |
+| Config file with auto-discovery | ✅ | ❌ |
+| Zero runtime dependencies (core) | ✅ | ❌ |
+
+## CLI
+
+```bash
+# Governance & evaluation
+cfa evaluate "intent" --catalog catalog.json --strict
+cfa policy check --signature signature.json --policy-bundle policies/prod.yaml
+cfa policy check --signature sig.json --catalog cat.json --strict --audit-log audit.jsonl
+
+# Validation (CI-ready with JSON output and exit codes)
+cfa catalog validate catalog.json --require-datasets --format json
+cfa signature validate signature.json --format json
+cfa policy validate policies/prod.yaml --format json
+
+# Audit & verification
+cfa audit show --id INTENT_ID --file audit.jsonl --format json
+cfa audit verify --file audit.jsonl
+
+# Policy rules
+cfa rules list
+cfa rules explain FAULT_CODE
+
+# Storage management
+cfa storage stats --db cfa.db --format json
+cfa storage cleanup --db cfa.db --retention 90
+cfa storage vacuum --db cfa.db
+
+# Lifecycle management
+cfa lifecycle evaluate --db cfa.db --window 30
+cfa lifecycle list --db cfa.db
+
+# Project health
+cfa status --format json
+
+# Bootstrap
+cfa init
+
+# Backends
+cfa backend list
+```
+
+## From Python
+
+```python
+from cfa.testing import evaluate, assert_passed
+
+result = evaluate(
+    "Join NFe with Clientes and persist to Silver",
+    catalog=MY_CATALOG,
+    policy_rules=my_rules,
+    backend="pyspark",
+)
+assert_passed(result)
+```
+
+### Policy check with audit
+
+```python
+from cfa.policy.engine import PolicyEngine
+from cfa.types import StateSignature
+
+signature = StateSignature.from_dict(signature_dict)
+engine = PolicyEngine(policy_bundle_version="prod-v1.0")
+result = engine.evaluate(signature)
+# result.action → approve / replan / block
+```
+
+### Runtime gate
+
+```python
+from cfa.runtime import RuntimeGate, GateConfig
+
+gate = RuntimeGate(
+    config=GateConfig(policy_bundle="prod_v1.0", sandbox="mock"),
+    catalog=PROD_CATALOG,
+)
+
+@gate.guard("aggregate sales with PII protected")
+def my_pipeline():
+    ...
+```
+
+### SQLite storage
+
+```python
+from cfa.storage import SqliteStorage
+
+store = SqliteStorage("cfa.db")
+store.ensure_schema()
+
+# Audit
+store.audit_append(event)
+
+# Execution records (lifecycle)
+store.execution_append(record_dict)
+
+# Lifecycle skills
+store.skill_upsert("hash_a", skill_data)
+```
+
+## Policy Bundles
+
+Declarative YAML policy rules — separate governance from code:
+
+```yaml
+# policies/prod-v1.yaml
+policy_bundle:
+  version: "prod-v1.0"
+  rules:
+    - name: forbid_raw_pii
+      condition: pii_in_protected_layer
+      action: block
+      fault_code: GOVERNANCE_RAW_PII
+      severity: critical
+      message: "PII in protected layer without anonymization."
+      remediation:
+        - "Apply sha256 on PII columns before the operation"
+```
+
+Validated at load time — unknown conditions, duplicate fault codes, and invalid enums are caught immediately.
+
+## Config File
+
+```yaml
+# cfa.yaml (auto-discovered by all commands)
+version: "1.0"
+storage:
+  backend: sqlite
+  path: cfa.db
+  retention_days: 90
+defaults:
+  catalog: .cfa/catalog.json
+  policy_bundle: .cfa/policies/prod-v1.yaml
+  backend: pyspark
+```
+
+## Backends
+
+Three governed code generation backends, all pluggable via `BackendRegistry`:
+
+| Backend | Language | Features |
+|---------|----------|----------|
+| `pyspark` | PySpark + Delta Lake | Merge, partition overwrite, PII anonymization |
+| `sql` | ANSI SQL | MERGE INTO, INSERT OVERWRITE, partition clauses |
+| `dbt` | dbt models + schema.yml | Config blocks, refs, not_null/unique tests, PII annotations |
+
+Each backend declares its own forbidden tokens for static validation.
+
+## MCP Server
+
+Expose CFA governance to any AI agent via Model Context Protocol:
+
+```json
+{
+  "mcpServers": {
+    "cfa": {
+      "command": "python",
+      "args": ["-m", "cfa.mcp"]
+    }
+  }
+}
+```
+
+5 tools: `cfa_evaluate_signature`, `cfa_describe_rules`, `cfa_explain_fault`, `cfa_audit_check`, `cfa_list_backends`.
+
+## Repository
+
+```text
+src/cfa/
+├── core/              Kernel, Planner, CodeGen, Conditions, Phases
+├── policy/            PolicyEngine, PolicyBundle, Catalog validation
+├── validation/        Static, Runtime, Signature validation
+├── audit/             AuditTrail, Context, Hashing
+├── observability/     Metrics, OTel, Notify, Indices, Promotion
+├── normalizer/        Rule-based normalizer, LLM normalizer
+├── execution/         Partial execution, State projection
+├── adapters/          LangGraph, OpenAI, CrewAI, AutoGen, DSPy
+├── backends/          PySpark, SQL, dbt (pluggable)
+├── sandbox/           Pluggable sandbox backend + registry + executor
+├── cli/               CLI commands by family (core/, governance/, reporting/, project/, infrastructure/)
+├── storage/           SQLite + JSONL backends (stats, cleanup, vacuum)
+├── mcp/               MCP server (JSON-RPC over stdio)
+├── reporting/         HTML reports
+├── runtime/           Production governance gate
+├── testing/           pytest-native evaluate() + fixtures
+├── config.py          CFA config (discovery, defaults)
+├── types.py           StateSignature, Fault, KernelResult
+└── _lazy.py           Reusable lazy loader for package __init__
+```
+
+## Docs
+
+All documentation at **[marquesantero.github.io/cfa](https://marquesantero.github.io/cfa/)**:
+
+- [Getting Started](https://marquesantero.github.io/cfa/docs/getting-started)
+- [CLI Reference](https://marquesantero.github.io/cfa/docs/cli)
+- [Policy Bundles](https://marquesantero.github.io/cfa/docs/policy-bundles)
+- [Backends](https://marquesantero.github.io/cfa/docs/backends)
+- [MCP Server](https://marquesantero.github.io/cfa/docs/mcp-server)
+- [Reporting](https://marquesantero.github.io/cfa/docs/reporting)
+- [Architecture Notes](https://marquesantero.github.io/cfa/docs/architecture-notes)
+- [FAQ](https://marquesantero.github.io/cfa/docs/faq)
+
+## License
+
+[MIT](./LICENSE) · [Antero Marques](https://github.com/marquesantero)

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/README.md

@@ -1,4 +1,4 @@
-# CFA v0.1.0
+# CFA v0.1.2
 
 [![CI](https://github.com/marquesantero/cfa/actions/workflows/ci.yml/badge.svg)](https://github.com/marquesantero/cfa/actions/workflows/ci.yml)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/pyproject.toml

@@ -4,10 +4,19 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cfa-kernel"
-version = "0.1.1"
+version = "0.1.3"
 description = "CFA — Governed execution for AI agents and data systems"
+readme = "README.md"
 requires-python = ">=3.11"
 license = { text = "MIT" }
+keywords = ["governance", "data", "ai", "policy", "audit", "pipeline", "compliance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: System :: Systems Administration",
+]
 
 [project.scripts]
 cfa = "cfa.cli:main"

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/src/cfa/__init__.py

@@ -6,7 +6,7 @@ Governed execution for AI agents and data systems.
 
 from cfa._lazy import LazyLoader
 
-__version__ = "0.1.1"
+__version__ = "0.1.3"
 
 __getattr__ = LazyLoader({
     "KernelOrchestrator": ("cfa.core.kernel", "KernelOrchestrator"),

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/src/cfa/cli/formatters.py

@@ -17,7 +17,7 @@ _ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
 # Force UTF-8 on Windows if possible
 if sys.platform == "win32":
     try:
-        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
     except Exception:
         pass
 

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/tests/test_user_journeys.py

@@ -34,7 +34,7 @@ class TestJourney1_FirstTimeUser:
     def test_01_install_and_version(self):
         """User: pip install cfa && python -c 'import cfa; print(cfa.__version__)'"""
         import cfa
-        assert cfa.__version__ == "0.1.0"
+        assert cfa.__version__.startswith("0.1.")
 
     def test_02_first_evaluate(self):
         """User: cfa evaluate 'my first governance check'"""

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/website/docs/api.md

@@ -4,7 +4,7 @@ sidebar_position: 16
 
 # API Reference
 
-Public classes and functions exported by CFA v0.1.0.
+Public classes and functions exported by CFA v0.1.2.
 
 ## `cfa.core.kernel`
 

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/website/docs/faq.md

@@ -68,8 +68,8 @@ Invariant I4: after every execution (success, partial, or failure), the `StatePr
 
 ## Can CFA handle streaming data?
 
-CFA v0.1.0 targets batch and micro-batch execution. Streaming support is planned for a future version. The architecture's concurrency model assumes `single_active_intent_per_target_scope`.
+CFA v0.1.2 targets batch and micro-batch execution. Streaming support is planned for a future version. The architecture's concurrency model assumes `single_active_intent_per_target_scope`.
 
 ## Is CFA production-ready?
 
-CFA v0.1.0 has 343 passing tests, a full CLI, MCP server, rich reporting, and framework adapters. It is designed for production governance gates. The core has been battle-tested through multiple refactors. As with any governance tool, deploy with monitoring and start with `cfa evaluate` in CI before moving to runtime gates.
+CFA v0.1.2 has 343 passing tests, a full CLI, MCP server, rich reporting, and framework adapters. It is designed for production governance gates. The core has been battle-tested through multiple refactors. As with any governance tool, deploy with monitoring and start with `cfa evaluate` in CI before moving to runtime gates.

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/website/docs/intro.md

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# CFA v0.1.0
+# CFA v0.1.2
 
 Governed execution for AI agents and data systems.
 

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/website/docs/whitepaper.md

@@ -2,7 +2,7 @@
 sidebar_position: 3
 ---
 
-# CFA v0.1.0 Whitepaper
+# CFA v0.1.2 Whitepaper
 
 Contextual Flux Architecture — Governed execution for AI agents and data systems.
 
@@ -197,7 +197,7 @@ Comprehensive test coverage across governance, resolution, lifecycle, kernel, ad
 
 ## 9. Conclusion
 
-CFA v0.1.0 establishes a governance kernel that bridges the gap between AI agent flexibility and production-grade safety. By formalizing intent, enforcing policy before execution, generating deterministic code, sandboxing runtime, projecting state, and maintaining tamper-evident audit trails, CFA provides the guardrails that AI-native data systems require to operate in regulated, high-stakes environments.
+CFA v0.1.2 establishes a governance kernel that bridges the gap between AI agent flexibility and production-grade safety. By formalizing intent, enforcing policy before execution, generating deterministic code, sandboxing runtime, projecting state, and maintaining tamper-evident audit trails, CFA provides the guardrails that AI-native data systems require to operate in regulated, high-stakes environments.
 
 The architecture is designed for **progressive adoption**: start with a single policy gate before an existing pipeline, then expand to full kernel orchestration as confidence grows. Every component is pluggable, every decision is auditable, and every state transition is recorded.
 

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/website/docusaurus.config.ts

@@ -111,7 +111,7 @@ const config: Config = {
   } satisfies Preset.ThemeConfig,
 
   customFields: {
-    version: '0.1.0',
+    version: '0.1.2',
   },
 };
 

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/api.md

@@ -4,7 +4,7 @@ sidebar_position: 16
 
 # Referência da API
 
-Classes e funções públicas exportadas pelo CFA v0.1.0.
+Classes e funções públicas exportadas pelo CFA v0.1.2.
 
 ## `cfa.core.kernel`
 

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/intro.md

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# CFA v0.1.0
+# CFA v0.1.2
 
 Execução governada para agentes de IA e sistemas de dados.
 

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/whitepaper.md

@@ -2,7 +2,7 @@
 sidebar_position: 3
 ---
 
-# Whitepaper CFA v0.1.0
+# Whitepaper CFA v0.1.2
 
 Contextual Flux Architecture — Execução governada para agentes de IA e sistemas de dados.
 

{cfa_kernel-0.1.1 → cfa_kernel-0.1.3}/website/src/pages/index.tsx

@@ -17,7 +17,7 @@ function HomepageHeader() {
           fontFamily: 'monospace', fontSize: '0.75rem', letterSpacing: '0.25em',
           color: '#3dffa0', textTransform: 'uppercase', marginBottom: '1rem',
         }}>
-          Technical Whitepaper · v0.1.0
+          Technical Whitepaper · v0.1.2
         </p>
         <h1 className="hero__title" style={{
           fontFamily: "'Syne', sans-serif", fontSize: '3.5rem', fontWeight: 800,

cfa_kernel-0.1.1/PKG-INFO

@@ -1,32 +0,0 @@
-Metadata-Version: 2.4
-Name: cfa-kernel
-Version: 0.1.1
-Summary: CFA — Governed execution for AI agents and data systems
-Project-URL: Homepage, https://marquesantero.github.io/cfa/
-Project-URL: Repository, https://github.com/marquesantero/cfa
-Project-URL: Documentation, https://marquesantero.github.io/cfa/docs/intro
-License: MIT
-License-File: LICENSE
-Requires-Python: >=3.11
-Provides-Extra: all
-Requires-Dist: mcp>=1.0; extra == 'all'
-Requires-Dist: openai>=1.0; extra == 'all'
-Requires-Dist: opentelemetry-api>=1.20; extra == 'all'
-Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'all'
-Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all'
-Requires-Dist: pyyaml>=6.0; extra == 'all'
-Provides-Extra: dev
-Requires-Dist: pytest-cov>=5.0; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: pyyaml>=6.0; extra == 'dev'
-Requires-Dist: ruff>=0.8; extra == 'dev'
-Provides-Extra: llm
-Requires-Dist: openai>=1.0; extra == 'llm'
-Provides-Extra: mcp
-Requires-Dist: mcp>=1.0; extra == 'mcp'
-Provides-Extra: otel
-Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
-Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'otel'
-Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
-Provides-Extra: yaml
-Requires-Dist: pyyaml>=6.0; extra == 'yaml'