cegraph 0.1.0a0__tar.gz

cegraph-0.1.0a0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,40 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: "Thanks for reporting a bug!"
+  - type: input
+    id: version
+    attributes:
+      label: cegraph version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: "OS, Python version, numpy version"
+    validations:
+      required: true

cegraph-0.1.0a0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,20 @@
+name: Feature Request
+description: Suggest a new feature
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem this feature solves
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

cegraph-0.1.0a0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    ignore:
+      - dependency-name: "actions/*"
+        update-types: ["version-update:semver-major"]

cegraph-0.1.0a0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cegraph-0.1.0a0/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+      - name: Type check with mypy
+        run: mypy src/cegraph
+      - name: Run tests
+        run: pytest tests/ -v --tb=short --cov=cegraph --cov-report=xml
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml

cegraph-0.1.0a0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.myenv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.so
+.env
+.DS_Store
+AGENTS.md

cegraph-0.1.0a0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml

cegraph-0.1.0a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keylordelrey
+
+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.

cegraph-0.1.0a0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: cegraph
+Version: 0.1.0a0
+Summary: Causal-aware execution runtime for production Python systems.
+Project-URL: Homepage, https://github.com/keyreyla/cegraph
+Project-URL: Repository, https://github.com/keyreyla/cegraph
+Project-URL: Issues, https://github.com/keyreyla/cegraph/issues
+Project-URL: Changelog, https://github.com/keyreyla/cegraph/blob/main/CHANGELOG.md
+License: MIT License
+        
+        Copyright (c) 2026 keylordelrey
+        
+        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.
+License-File: LICENSE
+Keywords: causal-graph,causal-inference,counterfactual,debugging,execution-graph,mlops,observability,production-ml,runtime,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-benchmark; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# cegraph
+
+**Causal-aware execution runtime for production Python systems.**
+
+[![CI](https://github.com/keyreyla/cegraph/actions/workflows/test.yml/badge.svg?event=push&branch=main)](https://github.com/keyreyla/cegraph/actions/workflows/test.yml)
+[![PyPI version](https://img.shields.io/pypi/v/cegraph?color=%2334D058&label=pypi)](https://pypi.org/project/cegraph)
+[![Python versions](https://img.shields.io/pypi/pyversions/cegraph?color=%2334D058)](https://pypi.org/project/cegraph)
+[![License](https://img.shields.io/github/license/keyreyla/cegraph)](LICENSE)
+
+[Installation](#installation) • [Quick Start](#quick-start) • [Why cegraph](#why-cegraph) • [Documentation](#documentation)
+
+</div>
+
+cegraph is a Python library that tracks causal dependencies in your execution pipelines, runs counterfactual simulations, and adapts to changing conditions — all with less than 4% runtime overhead.
+
+```python
+from cegraph import causal_node, CausalGraph, Context, counterfactual
+
+@causal_node(sensitivity=["price", "demand"])
+def fetch_market_data(symbol: str) -> dict:
+    return {"price": 100.0, "demand": 0.75, "symbol": symbol}
+
+@causal_node(sensitivity=["price"], constraint=lambda x: 50 <= x <= 500)
+def apply_pricing_strategy(base_price: float) -> float:
+    return base_price * 1.15
+
+graph = CausalGraph()
+graph.connect(fetch_market_data, apply_pricing_strategy)
+graph.validate()
+
+with Context(graph=graph) as ctx:
+    market = fetch_market_data("AAPL")
+    final_price = apply_pricing_strategy(market["price"])
+
+cf = counterfactual(
+    base_trace=ctx.tracer.records,
+    interventions={"fetch_market_data": {"price": 120.0, "demand": 0.95, "symbol": "AAPL"}},
+    confidence_threshold=0.8,
+)
+print(f"Impact: {cf.overall_impact:.3f}, Confidence: {cf.confidence:.3f}")
+```
+
+## Installation
+
+```bash
+pip install cegraph
+```
+
+Requires Python 3.10+. The only dependency is `numpy`.
+
+## Quick Start
+
+### 1. Define causal nodes
+
+Decorate your functions with `@causal_node` to mark them as causally-tracked execution units:
+
+```python
+from cegraph import causal_node
+
+@causal_node(sensitivity=["input_vars"])
+def preprocess(data: dict) -> float:
+    return sum(data.values()) / len(data)
+
+@causal_node(sensitivity=["threshold"], constraint=lambda x: 0 <= x <= 1)
+def classify(score: float) -> str:
+    return "high" if score > 0.5 else "low"
+```
+
+### 2. Build the causal graph
+
+Connect nodes to declare dependencies:
+
+```python
+from cegraph import CausalGraph
+
+graph = CausalGraph()
+graph.connect(preprocess, classify)
+graph.validate()  # detects cycles, validates type compatibility
+```
+
+### 3. Execute with tracing
+
+Run inside a `Context` to automatically capture causal traces:
+
+```python
+from cegraph import Context
+
+with Context(graph=graph, buffer_size=1000) as ctx:
+    data = {"a": 0.8, "b": 0.6}
+    features = preprocess(data)
+    result = classify(features)
+
+summary = ctx.tracer.summary()
+# {'classify': {'count': 1, 'mean_latency_ms': 0.12, 'p95_latency_ms': 0.12}}
+```
+
+### 4. Run counterfactual simulations
+
+Ask "what if" questions about your pipeline:
+
+```python
+from cegraph import counterfactual
+
+cf = counterfactual(
+    base_trace=ctx.tracer.records,
+    interventions={"preprocess": 0.9},  # what if score was 0.9?
+    n_perturbations=100,
+)
+print(cf.overall_impact, cf.confidence, cf.confidence_flag)
+```
+
+### 5. Optimize with constraints
+
+Detect constraint violations and auto-fallback:
+
+```python
+from cegraph import optimize
+
+opt = optimize(
+    context=ctx,
+    objective="minimize_latency",
+    constraints={"max_latency_ms": 50, "min_confidence": 0.7},
+)
+print(opt.status, opt.action_taken)
+# "ok", "fallback_cache", or "violated" with recommendations
+```
+
+## Why cegraph
+
+Production ML pipelines, pricing engines, and distributed systems fail when they rely on static assumptions. cegraph solves three specific problems:
+
+- **Root-cause analysis**: When accuracy drops, cegraph's causal trace tells you which node caused it — not just that something went wrong.
+- **What-if simulation**: Run counterfactuals inside your live pipeline without deploying a separate simulation environment.
+- **Adaptive fallback**: When constraints are violated (latency spikes, confidence drops), cegraph deterministically falls back to cached results or bypass mode.
+
+### Performance
+
+cegraph is designed for hot execution paths. The tracer uses a lock-free ring buffer, zero-copy hashing, and adaptive sampling to keep overhead under 4% — well below the 15% design constraint.
+
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [API Reference](docs/reference.md) | Full API documentation |
+| [Architecture](docs/explanation.md) | How cegraph works under the hood |
+| [Changelog](CHANGELOG.md) | Release history |

cegraph-0.1.0a0/README.md

@@ -0,0 +1,148 @@
+<div align="center">
+
+# cegraph
+
+**Causal-aware execution runtime for production Python systems.**
+
+[![CI](https://github.com/keyreyla/cegraph/actions/workflows/test.yml/badge.svg?event=push&branch=main)](https://github.com/keyreyla/cegraph/actions/workflows/test.yml)
+[![PyPI version](https://img.shields.io/pypi/v/cegraph?color=%2334D058&label=pypi)](https://pypi.org/project/cegraph)
+[![Python versions](https://img.shields.io/pypi/pyversions/cegraph?color=%2334D058)](https://pypi.org/project/cegraph)
+[![License](https://img.shields.io/github/license/keyreyla/cegraph)](LICENSE)
+
+[Installation](#installation) • [Quick Start](#quick-start) • [Why cegraph](#why-cegraph) • [Documentation](#documentation)
+
+</div>
+
+cegraph is a Python library that tracks causal dependencies in your execution pipelines, runs counterfactual simulations, and adapts to changing conditions — all with less than 4% runtime overhead.
+
+```python
+from cegraph import causal_node, CausalGraph, Context, counterfactual
+
+@causal_node(sensitivity=["price", "demand"])
+def fetch_market_data(symbol: str) -> dict:
+    return {"price": 100.0, "demand": 0.75, "symbol": symbol}
+
+@causal_node(sensitivity=["price"], constraint=lambda x: 50 <= x <= 500)
+def apply_pricing_strategy(base_price: float) -> float:
+    return base_price * 1.15
+
+graph = CausalGraph()
+graph.connect(fetch_market_data, apply_pricing_strategy)
+graph.validate()
+
+with Context(graph=graph) as ctx:
+    market = fetch_market_data("AAPL")
+    final_price = apply_pricing_strategy(market["price"])
+
+cf = counterfactual(
+    base_trace=ctx.tracer.records,
+    interventions={"fetch_market_data": {"price": 120.0, "demand": 0.95, "symbol": "AAPL"}},
+    confidence_threshold=0.8,
+)
+print(f"Impact: {cf.overall_impact:.3f}, Confidence: {cf.confidence:.3f}")
+```
+
+## Installation
+
+```bash
+pip install cegraph
+```
+
+Requires Python 3.10+. The only dependency is `numpy`.
+
+## Quick Start
+
+### 1. Define causal nodes
+
+Decorate your functions with `@causal_node` to mark them as causally-tracked execution units:
+
+```python
+from cegraph import causal_node
+
+@causal_node(sensitivity=["input_vars"])
+def preprocess(data: dict) -> float:
+    return sum(data.values()) / len(data)
+
+@causal_node(sensitivity=["threshold"], constraint=lambda x: 0 <= x <= 1)
+def classify(score: float) -> str:
+    return "high" if score > 0.5 else "low"
+```
+
+### 2. Build the causal graph
+
+Connect nodes to declare dependencies:
+
+```python
+from cegraph import CausalGraph
+
+graph = CausalGraph()
+graph.connect(preprocess, classify)
+graph.validate()  # detects cycles, validates type compatibility
+```
+
+### 3. Execute with tracing
+
+Run inside a `Context` to automatically capture causal traces:
+
+```python
+from cegraph import Context
+
+with Context(graph=graph, buffer_size=1000) as ctx:
+    data = {"a": 0.8, "b": 0.6}
+    features = preprocess(data)
+    result = classify(features)
+
+summary = ctx.tracer.summary()
+# {'classify': {'count': 1, 'mean_latency_ms': 0.12, 'p95_latency_ms': 0.12}}
+```
+
+### 4. Run counterfactual simulations
+
+Ask "what if" questions about your pipeline:
+
+```python
+from cegraph import counterfactual
+
+cf = counterfactual(
+    base_trace=ctx.tracer.records,
+    interventions={"preprocess": 0.9},  # what if score was 0.9?
+    n_perturbations=100,
+)
+print(cf.overall_impact, cf.confidence, cf.confidence_flag)
+```
+
+### 5. Optimize with constraints
+
+Detect constraint violations and auto-fallback:
+
+```python
+from cegraph import optimize
+
+opt = optimize(
+    context=ctx,
+    objective="minimize_latency",
+    constraints={"max_latency_ms": 50, "min_confidence": 0.7},
+)
+print(opt.status, opt.action_taken)
+# "ok", "fallback_cache", or "violated" with recommendations
+```
+
+## Why cegraph
+
+Production ML pipelines, pricing engines, and distributed systems fail when they rely on static assumptions. cegraph solves three specific problems:
+
+- **Root-cause analysis**: When accuracy drops, cegraph's causal trace tells you which node caused it — not just that something went wrong.
+- **What-if simulation**: Run counterfactuals inside your live pipeline without deploying a separate simulation environment.
+- **Adaptive fallback**: When constraints are violated (latency spikes, confidence drops), cegraph deterministically falls back to cached results or bypass mode.
+
+### Performance
+
+cegraph is designed for hot execution paths. The tracer uses a lock-free ring buffer, zero-copy hashing, and adaptive sampling to keep overhead under 4% — well below the 15% design constraint.
+
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [API Reference](docs/reference.md) | Full API documentation |
+| [Architecture](docs/explanation.md) | How cegraph works under the hood |
+| [Changelog](CHANGELOG.md) | Release history |

cegraph-0.1.0a0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cegraph"
+dynamic = ["version"]
+description = "Causal-aware execution runtime for production Python systems."
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10"
+keywords = [
+    "causal-inference", "runtime", "observability", "mlops",
+    "execution-graph", "counterfactual", "tracing", "debugging",
+    "causal-graph", "production-ml",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Monitoring",
+]
+dependencies = ["numpy>=1.24"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-benchmark", "pytest-cov>=4.0", "ruff", "mypy", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/keyreyla/cegraph"
+Repository = "https://github.com/keyreyla/cegraph"
+Issues = "https://github.com/keyreyla/cegraph/issues"
+Changelog = "https://github.com/keyreyla/cegraph/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/cegraph/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cegraph"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"*.py" = ["N818"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

cegraph-0.1.0a0/src/cegraph/__init__.py

@@ -0,0 +1,33 @@
+from cegraph._version import __version__
+from cegraph.causal.counterfactual import CounterfactualResult, ImpactScore, counterfactual
+from cegraph.causal.optimizer import OptimizationResult, optimize
+from cegraph.core.context import Context
+from cegraph.core.graph import CausalGraph
+from cegraph.core.node import causal_node
+from cegraph.core.tracer import CausalTracer, TraceRecord
+from cegraph.exceptions import (
+    CausalConstraintViolation,
+    CausalCycleError,
+    CausalTypeError,
+    CegraphError,
+    TracerOverflowWarning,
+)
+
+__all__ = [
+    "__version__",
+    "causal_node",
+    "CausalGraph",
+    "Context",
+    "CausalTracer",
+    "TraceRecord",
+    "counterfactual",
+    "CounterfactualResult",
+    "ImpactScore",
+    "optimize",
+    "OptimizationResult",
+    "CegraphError",
+    "CausalCycleError",
+    "CausalTypeError",
+    "CausalConstraintViolation",
+    "TracerOverflowWarning",
+]

cegraph-0.1.0a0/src/cegraph/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0a0"