fluxrules 0.1.0__tar.gz

fluxrules-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Every file in the repository requires review from the project owner.
+# GitHub enforces this when "Require review from Code Owners" is enabled
+# in the branch protection rule for main.
+* @saurabh2mishra

fluxrules-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  quality:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          version: ">=0.8"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install project dependencies
+        run: uv sync --extra dev --extra docs
+
+      - name: Ruff
+        run: uv run ruff check src/ tests/
+
+      - name: Mypy
+        run: uv run mypy src/fluxrules --ignore-missing-imports
+
+      - name: Quickstart contract (first-run experience)
+        run: uv run pytest tests/contract/test_quickstart_contract.py -q
+
+      - name: Non-performance test suite
+        run: uv run pytest tests/ -q -m "not performance"
+
+      - name: Docs snippet tests
+        run: uv run pytest tests/docs/test_doc_snippets.py -q
+
+      - name: MkDocs build
+        run: uv run mkdocs build
+
+      - name: Bandit security scan
+        run: uv run bandit -r src/fluxrules -c pyproject.toml
+
+      - name: Dependency audit
+        run: uv run pip-audit --skip-editable
+
+      - name: Fresh API-extra dependency audit
+        run: |
+          set -euo pipefail
+          api_env="$(mktemp -d)/venv"
+          uv venv --python "${{ matrix.python-version }}" "$api_env"
+          uv pip install --python "$api_env/bin/python" '.[api]'
+          api_site_packages="$("$api_env/bin/python" -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])')"
+          uv run --no-sync pip-audit --path "$api_site_packages"

fluxrules-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"          # API reference regenerates on source changes
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:      # allow manual deploys from the Actions tab
+
+permissions:
+  contents: write         # mkdocs gh-deploy pushes to the gh-pages branch
+
+jobs:
+  deploy:
+    name: Build and deploy MkDocs site
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history so git-revision-date plugins work
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          version: ">=0.8"
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install project with docs extras
+        run: uv sync --extra docs
+
+      - name: Configure git for gh-deploy
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Build and deploy to gh-pages branch
+        run: uv run mkdocs gh-deploy --force --clean --verbose

fluxrules-0.1.0/.github/workflows/package-artifacts.yml

@@ -0,0 +1,59 @@
+name: Package artifact gate
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    tags:
+      - "v*"
+  pull_request:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+jobs:
+  package-smoke:
+    name: Build + install smoke test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          version: ">=0.8"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Install each artifact in a clean venv and run a core smoke test
+        shell: bash
+        run: |
+          set -euo pipefail
+          for artifact in dist/*.tar.gz dist/*.whl; do
+            venv_dir=".artifact-venv-$(basename "$artifact" | tr -cs '[:alnum:]' '_')"
+            python -m venv "$venv_dir"
+            . "$venv_dir/bin/activate"
+            python -m pip install --upgrade pip --quiet
+            python -m pip install --force-reinstall "$artifact" --quiet
+            python scripts/artifact_smoke_test.py
+            deactivate
+            rm -rf "$venv_dir"
+          done

fluxrules-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,190 @@
+name: Release
+
+# Triggers only on version tags — never on branch pushes.
+# Pushing v0.1.0 starts build → smoke-test → (manual gate) → PyPI.
+on:
+  push:
+    tags:
+      - "v*"
+
+# No top-level permissions: every job declares its own minimal set.
+permissions: {}
+
+jobs:
+  # ── 1. Build ──────────────────────────────────────────────────────────────
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read   # checkout only
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history for SCM-based version tools
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          version: ">=0.8"
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Reject runs triggered by a tag that is not reachable from main.
+      # This prevents a tag pushed from a feature branch from publishing.
+      - name: Assert tag commit is on main
+        shell: bash
+        run: |
+          set -euo pipefail
+          git fetch origin main --depth=50
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::Tag $GITHUB_REF_NAME was pushed from a commit not on main."
+            echo "Only tags on main may trigger a release."
+            exit 1
+          fi
+          echo "tag-on-main-gate: $GITHUB_SHA is reachable from origin/main OK"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      # Verify the tag version matches pyproject.toml before uploading anything.
+      - name: Assert tag matches package version
+        shell: bash
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME}"           # e.g. "v0.1.0"
+          PKG_VERSION="$(python3 -c "
+          import tomllib, pathlib
+          print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])
+          ")"
+          EXPECTED_TAG="v${PKG_VERSION}"
+          if [ "$TAG" != "$EXPECTED_TAG" ]; then
+            echo "::error::Tag '$TAG' does not match pyproject.toml version 'v${PKG_VERSION}'."
+            echo "Update pyproject.toml and src/fluxrules/version.py, then re-tag."
+            exit 1
+          fi
+          echo "tag-version-gate: $TAG == v$PKG_VERSION OK"
+
+      # Verify both version fields are in sync — read version.py with grep,
+      # no package import needed (avoids pydantic not being installed yet).
+      - name: Assert pyproject.toml and version.py agree
+        shell: bash
+        run: |
+          set -euo pipefail
+          PY_VERSION="$(grep -m1 '^__version__' src/fluxrules/version.py | sed 's/.*"\(.*\)".*/\1/')"
+          PKG_VERSION="$(python3 -c "
+          import tomllib, pathlib
+          print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])
+          ")"
+          if [ "$PY_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::src/fluxrules/version.py (__version__='$PY_VERSION') differs from pyproject.toml ('$PKG_VERSION')."
+            exit 1
+          fi
+          echo "version-sync-gate: $PY_VERSION OK"
+
+      - name: twine check
+        run: |
+          uv tool install twine
+          uv tool run twine check dist/* --strict
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  # ── 2. Install smoke test (sdist + wheel, 3 Python versions) ─────────────
+  smoke-test:
+    name: Install smoke (${{ matrix.python-version }})
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Smoke-test each artifact
+        shell: bash
+        run: |
+          set -euo pipefail
+          for artifact in dist/*.tar.gz dist/*.whl; do
+            venv_dir="$(mktemp -d)/smoke-venv"
+            python -m venv "$venv_dir"
+            . "$venv_dir/bin/activate"
+            pip install --upgrade pip --quiet
+            pip install --force-reinstall "$artifact" --quiet
+            python scripts/artifact_smoke_test.py
+            deactivate
+            rm -rf "$venv_dir"
+          done
+
+  # ── 3. Publish to PyPI ───────────────────────────────────────────────────
+  #
+  # TestPyPI skipped: name is unavailable on test.pypi.org.
+  # Validation is covered by build gates + smoke-test on 3 Python versions.
+  #
+  # Requires secret PYPI_API_TOKEN set at:
+  #   https://github.com/saurabh2mishra/fluxrules/settings/secrets/actions
+  #
+  # The pypi GitHub environment gate gives a manual confirmation click
+  # before the upload proceeds. Set up at:
+  #   https://github.com/saurabh2mishra/fluxrules/settings/environments
+  #
+  publish-pypi:
+    name: Publish → PyPI
+    needs: [build, smoke-test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fluxrules
+    permissions:
+      contents: write   # create GitHub release
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          print-hash: true
+          verbose: true
+
+      # Create a GitHub release automatically on successful PyPI publish.
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          fail_on_unmatched_files: true

fluxrules-0.1.0/.gitignore

@@ -0,0 +1,74 @@
+# Python virtual environments
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# Python bytecode and build artifacts
+# Python creates these directories throughout the source and test trees.
+**/__pycache__/
+*.py[cod]
+*.so
+*.pyo
+*.pyd
+*.egg-info/
+.eggs/
+dist/
+build/
+site/
+*.egg
+
+# Test, coverage, and tooling caches
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# Local environment and secrets
+.env
+.env.*
+*.local
+*.pem
+credentials*.json
+
+# Editors and OS files
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Project-specific generated files
+logs/
+*.log
+/.github/agents/
+/.github/skills/
+
+# SQLite / database runtime artifacts
+*.db
+*.sqlite
+*.sqlite3
+*.db-wal
+*.db-shm
+*_wal
+*_shm
+rune_engine.db
+fluxrules_dev.db
+rule_engine.db
+rule_engine.db-wal
+rule_engine.db-shm
+
+# Optional generated docs/assets
+mkdocs_material/
+
+# Claude Code — keep local only, do not publish to remote.
+.claude/

fluxrules-0.1.0/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-06
+
+First release intended for publication. The changes below tighten the public
+API surface so that one concept has one name and one type. `0.0.1` was never
+published, so these are breaking relative to an unreleased baseline only and
+carry no deprecation shims — carrying a shim for `matched_rule_ids` was
+rejected precisely because the name's meaning was the defect.
+
+### Changed — breaking
+
+- **One `EvaluationResult`.** There were two classes of that name: the domain
+  one, whose `matched_rule_ids` meant *the rules that fired*, and the engine
+  one, whose `matched_rule_ids` meant *the rules discovery considered*. Both
+  were exported as `EvaluationResult`, so the same attribute answered a
+  different question depending on which function you called, and the engine's
+  answer was a superset that silently over-reported matches. They are now a
+  single class owned by `fluxrules.domain.models`;
+  `fluxrules.engine.infrastructure.EvaluationResult` re-exports it.
+- **`fired_rules` is the only name for what matched.** `matched_rule_ids` is
+  removed from the attribute set, the constructor, and the persisted schema.
+  `candidate_rule_ids` remains the discovery prefilter's output and is
+  guaranteed to be a superset of `fired_rules` on every evaluation path,
+  including the reference evaluator.
+- **`Rule(...)` no longer touches the database.** `persist` now defaults to
+  `False`, so constructing a rule is a pure in-memory operation; previously the
+  default `True` meant importing a module that defined rules opened a
+  connection and created a `.db` file, then swallowed any failure as a log
+  warning. Persist explicitly with the new `Rule.save()` or `persist=True`.
+  The redundant `except Exception` around persistence is gone —
+  `PersistenceManager.persist_rule` already degrades to a local ID, so anything
+  escaping it is a real fault.
+- **`RuleBuilder.build()` returns `Rule`**, not the internal `EngineRule`, so a
+  built rule goes straight into `load_rules()` or `evaluate()`. Use the new
+  `build_engine_rule()` for the internal representation. `RuleBuilder`'s
+  `persist` default is now `False` to match `Rule`.
+- **`evaluate()` and `validate()` take rules directly.** Both accept a single
+  `Rule`, any iterable of `Rule`, or a `Ruleset`; the first parameter is
+  renamed `ruleset` → `rules`. Building a `Ruleset` of `to_engine_rule()`
+  conversions is no longer required to evaluate a list of rules.
+- **`explain()` returns `fired_rules`** instead of `matched_rules`, matching
+  `EvaluationResult`. The HTTP API's own `matched_rules` response field is a
+  separate wire contract and is unchanged.
+- The `evaluation_results` table's `matched_rule_ids` column is now
+  `fired_rules`. The table is created by `create_all()` rather than Alembic, so
+  an existing development database needs to be recreated.
+
+### Fixed
+
+- `RuleBuilder()` with no explicit ID allocated from a second, builder-local
+  sequential generator that also started at 1, so the first built rule and the
+  first directly-constructed rule were assigned the same ID and evaluating them
+  together failed with "Ruleset has duplicate rule ids". The builder now defers
+  to the same shared generator `Rule` uses.
+- `docs/rule-builder.md` documented a `RuleBuilder` API that did not exist
+  (`.domain()`, `.tags()`, `.condition_dsl()`, and a snippet that was not valid
+  Python) while never demonstrating the real builder. Every block on the page
+  is now executable and covered by the documentation harness.
+
+### Added
+
+- `Rule.save()` — explicit persistence for a rule built in memory.
+- `RuleBuilder`, `ConditionBuilder`, and the `Rules` input alias are exported
+  from the top-level `fluxrules` namespace.
+- `RuleBuilder.build_engine_rule()` for the internal `EngineRule` shape.
+- A quickstart contract test (`tests/contract/test_quickstart_contract.py`) that
+  runs the documented ten-line example in a clean subprocess, asserts it emits
+  no warnings, and asserts it writes nothing to disk. CI runs it as its own step
+  ahead of the main suite so a broken first-run experience fails loudly.
+
+## [0.0.1] - 2026-09-14
+
+Initial, unpublished development version. FluxRules is a Python rule-evaluation
+library built on a single engine, PHREAK, with stateless (default) and streaming
+evaluation modes.
+
+### Added
+
+- Core evaluation API — `evaluate()`, `validate()`, `explain()` over a typed
+  `Ruleset` of rules, with a curated public `__all__` and a shipped `py.typed`
+  marker.
+- PHREAK engine (`PhreakEngine`): lazy, agenda-driven evaluation in stateless
+  (default) and streaming modes. Correctness is checked against the
+  dependency-free `ReferenceEvaluator` oracle and by stateless/streaming parity.
+- Condition operators — 13 distinct operators plus 6 word aliases: `==`/`eq`,
+  `!=`/`ne`, `>`/`gt`, `>=`/`gte`, `<`/`lt`, `<=`/`lte`, `in`, `not_in`,
+  `contains`, `not_contains`, `starts_with`, `ends_with`, `regex`; combined with
+  arbitrary AND/OR/NOT nesting.
+- Extensibility — public `register_engine()` / `unregister_engine()` (a custom
+  `BaseEngine` becomes selectable via `get_engine()`, the HTTP API, and the CLI
+  `--engine` flag; the built-in engine is protected), registries for custom
+  operators/actions/transforms/validators, entry-point auto-discovery
+  (`fluxrules.plugins.discovery.load_plugins`), and a public conformance kit
+  (`fluxrules.testing.assert_engine_contract`).
+- Fact pipeline — `Flatten`, `Rename`, `Defaults`, `Require`, `FieldType`, and
+  user-defined transforms.
+- Validation framework (structure, conflicts, dead/redundant rules) and an audit
+  trail with integrity hashing.
+- Optional adapters behind extras: FastAPI HTTP API (`api`), SQLAlchemy/Alembic
+  persistence (`sql`), Redis sessions (`redis`), OpenTelemetry (`otel`), YAML
+  rules (`yaml`), and a Typer CLI (`cli`).
+- Documentation (MkDocs Material), 31 runnable examples, a suite of 2,000+ tests,
+  and a CI-gated scale test.
+
+### Security
+
+- Scoped flake8-bandit (`S`) ruff rule set enforced in the lint gate
+  (exec/eval/pickle/marshal/weak-hash/SQL-injection/try-except-pass).
+- CI security job (`bandit` + `pip-audit`) and a pull-request `dependency-review`
+  job; SPDX SBOM generation and Sigstore signing in the release workflow.
+- `SECURITY.md` (supported versions, response targets, coordinated disclosure), a
+  threat model in `docs/security.md`, `CODEOWNERS`, and branch-protection
+  guidance in `CONTRIBUTING.md`.