provena 0.6.0__tar.gz

provena-0.6.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,73 @@
+name: Bug Report
+description: Report a bug in Provena
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill in the details below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+      placeholder: "When I call trail.log() with..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code or steps to reproduce the issue.
+      render: python
+      placeholder: |
+        from provena import ContextTrail
+        trail = ContextTrail(backend="memory")
+        # ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened. Include error messages or tracebacks.
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Provena version
+      placeholder: "0.5.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Storage backend
+      options:
+        - SQLite (default)
+        - InMemory
+        - Not applicable
+    validations:
+      required: true

provena-0.6.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://github.com/rajfirke/provena#readme
+    about: Read the README for usage guides and API reference.
+  - name: Security Vulnerability
+    url: https://github.com/rajfirke/provena/security/advisories/new
+    about: Report security vulnerabilities privately (do NOT open a public issue).

provena-0.6.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,46 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea for Provena? We'd love to hear it.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What problem does this feature solve? Why do you need it?
+      placeholder: "I'm trying to govern context from [framework] but there's no adapter..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How do you think this should work? Code examples welcome.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What workarounds or alternatives have you tried?
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Core (trail, storage, models)
+        - Validator (provenance, freshness)
+        - Integration (LangChain, LlamaIndex, other framework)
+        - Exporter (OpenTelemetry, other)
+        - CLI
+        - Documentation
+        - Other
+    validations:
+      required: true

provena-0.6.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## What does this PR do?
+
+<!-- A clear description of what this PR changes and why. -->
+
+## Checklist
+
+- [ ] Tests added/updated for the change
+- [ ] `ruff check src/ tests/` passes
+- [ ] `ruff format --check src/ tests/` passes
+- [ ] `mypy src/provena/` passes
+- [ ] `pytest` passes with no failures
+- [ ] CHANGELOG.md updated (if user-facing change)
+
+## Related Issues
+
+<!-- Link any related issues: Fixes #123, Relates to #456 -->

provena-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,cli,otel]"
+          pip install opentelemetry-sdk
+      - name: Lint
+        run: ruff check src/ tests/
+      - name: Format check
+        run: ruff format --check src/ tests/
+      - name: Type check
+        run: mypy src/provena/
+      - name: Test
+        run: pytest --cov=provena --cov-report=xml -v
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.xml

provena-0.6.0/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Check distribution
+        run: |
+          pip install twine
+          twine check dist/*
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build, publish-testpypi]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${{ github.ref_name }}" --generate-notes

provena-0.6.0/.gitignore

@@ -0,0 +1,45 @@
+# Planning & research docs (not part of the codebase)
+project-context/
+blogs/
+roadmap/
+plan/
+IMPLEMENTATION-BLUEPRINT.md
+info.md
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Provena runtime
+*.db
+provena.db
+
+# OS
+.DS_Store
+Thumbs.db

provena-0.6.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to Provena are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.6.0] - 2026-07-17
+
+### Added
+- Google-style docstrings on all public API classes and methods
+- PyPI trusted publishing via GitHub Actions with OIDC authentication
+- PyPI version and download badges in README
+- `ContextTrail.query()` filters for exact provenance and freshness status values
+
+## [0.5.0] - 2026-07-15
+
+### Added
+- **Framework integrations**: LangChain `ProvenaCallback` and LlamaIndex `ProvenaPostprocessor`
+- **OpenTelemetry export**: Span emission for every governance event (`provena[otel]`)
+- **CLI tools**: `provena audit`, `provena verify`, `provena report`, `provena summary`
+- **FreshnessChecker**: Regex-based temporal detection (ISO dates, month-year, quarters, contextual years)
+- **HMAC-SHA256 signing**: Optional compliance mode with external signing key
+- **Config validation**: `max_age_days` and `max_content_bytes` validated on construction
+- **InMemoryBackend**: For testing without filesystem side effects
+- **SQLite schema versioning**: `user_version` pragma with automatic migration
+- **`trail.annotate()`**: Human oversight annotations (EU AI Act Art. 14)
+- **`trail.explain()`/`summary()`**: Governance transparency (EU AI Act Art. 13)
+- **Error resilience**: Governance failures never crash user code
+- **Content type dispatch**: Automatic handling of str, bytes, list, dict, LangChain Documents
+- **226 tests** with 89% coverage across all components
+
+### Architecture
+- Pure Python, zero stdlib-only dependencies for core
+- SHA-256 hash-chained Merkle audit trail
+- Frozen dataclasses with slots for all models
+- Per-instance threading locks for thread safety
+- Append-only SQLite with WAL mode
+
+## [0.1.0] - 2026-07-13
+
+### Added
+- Initial implementation: `ContextTrail`, `@trail.track` decorator
+- Core models: `ContextEntry`, `TrailRecord`, `ProvenanceMetadata`, `ValidationResult`
+- `ProvenanceValidator` with configurable required fields
+- `HashChain` with SHA-256
+- `SQLiteBackend` with append-only storage
+- `ContextSource` enum: retriever, tool, agent, memory, mcp, custom

provena-0.6.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,62 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at **rajfirke on GitHub**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

provena-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to Provena
+
+Thanks for your interest in contributing to Provena! This document covers everything you need to get started.
+
+## Development Setup
+
+```bash
+# Clone and install
+git clone https://github.com/rajfirke/provena.git
+cd provena
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,cli,otel]"
+pip install opentelemetry-sdk  # for OTel tests
+
+# Verify everything works
+pytest
+ruff check src/ tests/
+mypy src/provena/
+```
+
+## Project Structure
+
+```
+src/provena/
+├── __init__.py              # Public API
+├── models.py                # Core data types (ContextEntry, TrailRecord, etc.)
+├── hasher.py                # SHA-256 / HMAC-SHA256 hash chain
+├── storage.py               # SQLite + InMemory backends
+├── trail.py                 # ContextTrail engine + @track decorator
+├── validators/
+│   ├── provenance.py        # Provenance validation (VALID/MISSING/INCOMPLETE)
+│   └── freshness.py         # Freshness checking with regex temporal detection
+├── exporters/
+│   └── otel.py              # OpenTelemetry span export
+├── integrations/
+│   ├── langchain.py         # LangChain BaseCallbackHandler
+│   └── llamaindex.py        # LlamaIndex BaseNodePostprocessor
+└── cli/
+    └── main.py              # Click-based CLI (audit/verify/report/summary)
+```
+
+## How to Contribute
+
+### Adding a New Validator
+
+1. Create `src/provena/validators/your_validator.py`
+2. Follow the pattern in `provenance.py` — accept a `ContextEntry`, return a result dataclass
+3. Add tests in `tests/test_your_validator.py`
+4. Integrate into `trail.py` `_log_internal()` if it should run on every log call
+
+### Adding a New Integration
+
+1. Create `src/provena/integrations/your_framework.py`
+2. Use try/except for the framework import (see `langchain.py` for the pattern)
+3. Add the framework as an optional dependency in `pyproject.toml`
+4. Add tests using mock objects (see `test_integrations.py`)
+
+### Adding a New Storage Backend
+
+1. Implement the `StorageBackend` protocol from `storage.py`
+2. Required methods: `append`, `get`, `get_last`, `count`, `all_records`, `query`, `add_annotation`, `close`
+3. Add tests that verify parity with `InMemoryBackend`
+
+## Code Standards
+
+- **Formatter**: `ruff format`
+- **Linter**: `ruff check` (rules: E, F, I, N, UP, W, B, SIM, RUF)
+- **Type checker**: `mypy --strict`
+- **Tests**: `pytest` with `pytest-cov` — aim for 90%+ coverage
+- **Python**: 3.10+ (use `from __future__ import annotations`)
+
+All checks must pass before merging. CI runs automatically on every PR.
+
+## Pull Request Process
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes with tests
+3. Run the full check suite:
+   ```bash
+   ruff check src/ tests/
+   ruff format --check src/ tests/
+   mypy src/provena/
+   pytest --cov=provena
+   ```
+4. Open a PR with a clear description of what and why
+5. Respond to review feedback
+
+## Reporting Bugs
+
+Use the [bug report template](https://github.com/rajfirke/provena/issues/new?template=bug_report.yml) on GitHub Issues.
+
+## Requesting Features
+
+Use the [feature request template](https://github.com/rajfirke/provena/issues/new?template=feature_request.yml) on GitHub Issues.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

provena-0.6.0/LICENSE

@@ -0,0 +1,161 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but not
+      limited to compiled object code, generated documentation, and
+      conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the original
+      version of the Work and any modifications or additions to that Work or
+      Derivative Works thereof, that is intentionally submitted to the Licensor
+      for inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner. For
+      the purposes of this definition, "submitted" means any form of electronic,
+      verbal, or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed by,
+      or on behalf of, the Licensor for the purpose of discussing and improving the
+      Work, but excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+      of whom a Contribution has been received by the Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of this
+      License, each Contributor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+      reproduce, prepare Derivative Works of, publicly display, publicly perform,
+      sublicense, and distribute the Work and such Derivative Works in Source or
+      Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of this
+      License, each Contributor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable (except as stated in
+      this section) patent license to make, have made, use, offer to sell, sell,
+      import, and otherwise transfer the Work, where such license applies only
+      to those patent claims licensable by such Contributor that are necessarily
+      infringed by their Contribution(s) alone or by combination of their
+      Contribution(s) with the Work to which such Contribution(s) was submitted.
+
+   4. Redistribution. You may reproduce and distribute copies of the Work or
+      Derivative Works thereof in any medium, with or without modifications, and
+      in Source or Object form, provided that You meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works a
+          copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices stating
+          that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that You
+          distribute, all copyright, patent, trademark, and attribution notices
+          from the Source form of the Work, excluding those notices that do not
+          pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its distribution,
+          then any Derivative Works that You distribute must include a readable
+          copy of the attribution notices contained within such NOTICE file,
+          excluding any notices that do not pertain to any part of the Derivative
+          Works, in at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within the Source form
+          or documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and wherever such
+          third-party notices normally appear. The contents of the NOTICE file are
+          for informational purposes only and do not modify the License. You may
+          add Your own attribution notices within Derivative Works that You
+          distribute, alongside or as an addendum to the NOTICE text from the Work,
+          provided that such additional attribution notices cannot be construed as
+          modifying the License.
+
+      You may add Your own copyright statement to Your modifications and may
+      provide additional or different license terms and conditions for use,
+      reproduction, or distribution of Your modifications, or for any such
+      Derivative Works as a whole, provided Your use, reproduction, and
+      distribution of the Work otherwise complies with the conditions stated
+      in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise, any
+      Contribution intentionally submitted for inclusion in the Work by You to
+      the Licensor shall be under the terms and conditions of this License,
+      without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade names,
+      trademarks, service marks, or product names of the Licensor, except as
+      required for reasonable and customary use in describing the origin of the
+      Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+      writing, Licensor provides the Work (and each Contributor provides its
+      Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+      ANY KIND, either express or implied, including, without limitation, any
+      warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
+      FITNESS FOR A PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory, whether in
+      tort (including negligence), contract, or otherwise, unless required by
+      applicable law (such as deliberate and grossly negligent acts) or agreed to
+      in writing, shall any Contributor be liable to You for damages, including
+      any direct, indirect, special, incidental, or consequential damages of any
+      character arising as a result of this License or out of the use or inability
+      to use the Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee for,
+      acceptance of support, warranty, indemnity, or other liability obligations
+      and/or rights consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Raj Firke
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.