llm-beacon 0.1.0__tar.gz

llm_beacon-0.1.0/.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "docs",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["--prefix", "website", "run", "dev", "--", "--port", "4321"],
+      "port": 4321
+    }
+  ]
+}

llm_beacon-0.1.0/.gitattributes

@@ -0,0 +1,6 @@
+# Snapshot files are compared byte-for-byte; never let git rewrite line endings.
+snapshots/** text eol=lf
+*.py text eol=lf
+*.rs text eol=lf
+*.md text eol=lf
+*.yaml text eol=lf

llm_beacon-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: A block returned something unexpected, or behaved differently across runs, machines or versions
+labels: bug
+---
+
+**Block and call**
+
+```python
+# the exact call, with the exact input (repr() of strings helps with invisible characters)
+```
+
+**Expected output**
+
+**Actual output** (full exception including `code` and position, if any)
+
+**Determinism issue?** Does the output differ between runs, machines, Python versions or beacon versions? Which?
+
+**Environment**
+- beacon version (`beacon.__version__`):
+- Python version / OS / CPU:

llm_beacon-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: A new format, keyword, detector, option or integration
+labels: enhancement
+---
+
+**What should beacon handle?** Include a real example input (e.g. an LLM response) and the output you expect.
+
+**Which block?**
+
+**Why can't this be done with existing options?**
+
+Note: beacon only adds behaviour that stays deterministic and explicit. Options that "repair" malformed input are out of scope.

llm_beacon-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,8 @@
+## What changed
+
+## Determinism checklist
+- [ ] No new hidden inputs (clock, env vars, locale, global state)
+- [ ] No `unwrap()`/`expect()`/`panic!` outside tests
+- [ ] Error messages / codes unchanged, or listed under "Behaviour changes" in CHANGELOG.md
+- [ ] Snapshot diffs (if any) are intended and explained here
+- [ ] Tests added

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

@@ -0,0 +1,107 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  # Snapshot tests run in "check" mode: missing or changed snapshots fail.
+  CI: "true"
+
+jobs:
+  lint:
+    name: Python lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install ruff
+      - run: ruff check python tests examples benches
+
+  rust:
+    name: Rust (fmt, clippy, unit tests)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --check
+      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo clippy --all-targets --no-default-features -- -D warnings
+      - run: cargo test --no-default-features
+
+  python:
+    name: Python ${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Build and install wheel
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip maturin pytest pyyaml pydantic
+          maturin build --release --out dist
+          python -m pip install dist/*.whl
+      - name: Tests (snapshots must match byte for byte on every OS)
+        run: python -m pytest -p no:cacheprovider
+      - name: Overhead benchmark (< 0.5 ms per block)
+        run: python benches/determinism_overhead.py --number 500
+
+  locale:
+    name: Locale independence (LANG=C)
+    runs-on: ubuntu-latest
+    env:
+      LANG: C
+      LC_ALL: C
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: |
+          python -m pip install maturin pytest pyyaml pydantic
+          maturin build --release --out dist
+          python -m pip install dist/*.whl
+          python -X utf8 -m pytest -p no:cacheprovider
+
+  integrations:
+    name: Framework integrations
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: |
+          python -m pip install maturin pytest pyyaml
+          maturin build --release --out dist
+          python -m pip install dist/*.whl "langchain-core>=1" "llama-index-core>=0.14" "pydantic-ai-slim>=2" "dspy>=3" openai
+      - run: python -m pytest -p no:cacheprovider tests/test_integration_*.py
+      - name: Examples run offline
+        env:
+          PYDANTIC_AI_NO_BANNER: "1"
+        run: |
+          for f in examples/0[1-7]_*.py; do echo "::group::$f"; python "$f"; echo "::endgroup::"; done
+          python -m pytest -p no:cacheprovider examples/08_snapshot_testing_your_app.py

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

@@ -0,0 +1,69 @@
+name: Docs site
+
+# Builds the documentation site (Astro + Starlight) and the playground's
+# WebAssembly engine, and deploys to GitHub Pages.
+# One-time setup: Settings → Pages → Source: "GitHub Actions".
+
+on:
+  push:
+    branches: [main]
+    paths: ["website/**", "src/**", "Cargo.toml", "Cargo.lock", ".github/workflows/docs.yml"]
+  pull_request:
+    paths: ["website/**", "src/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: website/wasm
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+      - id: pages
+        uses: actions/configure-pages@v5
+      - name: Install
+        working-directory: website
+        run: npm ci
+      - name: Build playground engine (Rust → WebAssembly)
+        working-directory: website
+        run: npm run wasm
+      - name: Build site
+        working-directory: website
+        env:
+          SITE_URL: ${{ steps.pages.outputs.origin }}
+          BASE_PATH: ${{ steps.pages.outputs.base_path }}
+          PUBLIC_REPO_URL: ${{ github.server_url }}/${{ github.repository }}
+        run: npm run build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/dist
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -0,0 +1,69 @@
+name: Release
+
+# Builds abi3 wheels (one per platform covers Python 3.10+) and an sdist, then
+# publishes to PyPI with trusted publishing when a v* tag is pushed.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  wheels:
+    name: Wheels ${{ matrix.platform.target }} (${{ matrix.platform.os }})
+    runs-on: ${{ matrix.platform.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - { os: ubuntu-latest, target: x86_64, manylinux: auto }
+          - { os: ubuntu-latest, target: aarch64, manylinux: auto }
+          - { os: ubuntu-latest, target: x86_64, manylinux: musllinux_1_2 }
+          - { os: macos-latest, target: aarch64 }
+          - { os: macos-latest, target: x86_64 }
+          - { os: windows-latest, target: x64 }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          manylinux: ${{ matrix.platform.manylinux }}
+          args: --release --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.platform.os }}-${{ matrix.platform.target }}-${{ strategy.job-index }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  publish:
+    name: Publish to PyPI
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

llm_beacon-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+/target
+.venv/
+__pycache__/
+*.py[cod]
+*.so
+*.pyd
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.coverage
+
+# Docs site
+website/node_modules/
+website/dist/
+website/.astro/
+website/wasm/target/

llm_beacon-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to beacon are documented here. beacon follows semantic
+versioning, with the extra compatibility rules in
+[docs/determinism_guarantees.md](docs/determinism_guarantees.md): patch
+releases never change block output, including error messages.
+
+Each release lists **Behaviour changes** separately. Those are any
+input whose output differs from the previous release.
+
+## [0.1.0] - unreleased
+
+First release, published on PyPI as `llm-beacon` (import name `beacon`).
+
+### Added
+
+- Blocks, implemented in Rust via PyO3 0.30: `template`, `template_variables`,
+  `extract_json`, `extract_json_detailed`, `parse_tool_call`,
+  `parse_tool_calls`, `validate_schema`, `schema_errors`, `normalize`,
+  `hash_content`, `redact`, `detect_pii`, `retry.classify`,
+  `retry.backoff_delay`, `retry.call`.
+- `Pipeline` / `Block` composition with hash traces.
+- Snapshot testing: `assert_snapshot`, pytest `snapshot` fixture,
+  `--beacon-snapshot` option, `python -m beacon.snapshots update|check`.
+- Integrations: OpenAI SDK, LangChain, LlamaIndex, Pydantic AI, DSPy.
+- abi3 wheels for CPython 3.10+.
+
+### Pinned data versions
+
+- Unicode tables: 18.0.0 (`beacon.UNICODE_VERSION`).
+- Canonical hash encoding: v1.
+- Snapshot file format: v1.

llm_beacon-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to beacon
+
+Thanks for helping. Issues and pull requests go to
+[IND-Anshuman/beacon](https://github.com/IND-Anshuman/beacon).
+
+beacon's value is its contract: same input, same output, on every machine,
+across versions. Every change is reviewed against
+[docs/determinism_guarantees.md](docs/determinism_guarantees.md).
+
+## Setup
+
+```bash
+git clone https://github.com/IND-Anshuman/beacon.git && cd beacon
+python -m venv .venv
+. .venv/bin/activate              # Windows: .venv\Scripts\activate
+pip install maturin pytest pyyaml pydantic
+maturin develop                   # builds the Rust extension into the venv
+pytest
+cargo test --no-default-features  # pure-Rust core, no Python needed
+```
+
+Optional, for the integration tests:
+`pip install langchain-core llama-index-core pydantic-ai-slim dspy openai`.
+
+### Windows without Visual Studio Build Tools
+
+The default Rust target on Windows (`x86_64-pc-windows-msvc`) needs the MSVC
+linker. If you don't have it, the GNU toolchain works for local development:
+
+```bash
+rustup toolchain install stable-x86_64-pc-windows-gnu
+rustup override set stable-x86_64-pc-windows-gnu
+# PyO3's raw-dylib linking needs binutils' `as`, which the GNU toolchain lacks;
+# link against the Python DLL directly instead:
+export PYO3_USE_RAW_DYLIB=0
+export RUSTFLAGS="-L native=<path to your Python install dir containing python3.dll>"
+maturin develop
+```
+
+## Rules for changes
+
+1. **No hidden inputs.** Blocks never read the clock, environment variables,
+   the locale, files or the network, and they keep no state between calls.
+   Every option is an explicit parameter.
+2. **No `unwrap()`/`expect()`/`panic!` in non-test Rust code.** A panic kills
+   the user's Python process. Clippy enforces this (`cargo clippy
+   --all-targets -- -D warnings`).
+3. **Never repair input silently.** Strict parsing, explicit errors.
+4. **Error messages are API.** Don't change a message or `code` in a patch
+   release. New errors and new messages go in a minor release, listed under
+   "Behaviour changes" in `CHANGELOG.md`, and are added to the error code
+   table in `docs/blocks_reference.md`.
+5. **Snapshot changes need justification.** If `pytest` reports a snapshot
+   diff, read it. If the change is intended, run
+   `python -m beacon.snapshots update`, commit the updated `.yaml` files, and
+   explain the change in the PR.
+6. **Positions are code points.** Anything reported to Python as an offset
+   counts Unicode code points, not bytes.
+7. **Tests with every change.** Add unit tests and, for new behaviour, a
+   snapshot case in the block's corpus.
+
+## Layout
+
+```
+src/            Rust core (pure; no pyo3 types) + src/lib.rs, src/convert.rs (bindings)
+python/beacon/  Python package: wrappers, errors, Pipeline, snapshots, integrations
+tests/          pytest suite (unit + snapshot corpora + integrations)
+snapshots/      golden files, compared byte for byte in CI on Linux/macOS/Windows
+benches/        per-block overhead benchmark (< 0.5 ms budget)
+examples/       runnable examples (offline, fake models)
+docs/           user documentation and the determinism contract
+```