piighost 0.1.0__tar.gz

piighost-0.1.0/.cz.toml

@@ -0,0 +1,7 @@
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "$version"
+version_scheme = "pep440"
+version_provider = "uv"
+update_changelog_on_bump = true
+major_version_zero = true

piighost-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,67 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill in as much detail as possible.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal code or steps to reproduce the behavior.
+      placeholder: |
+        ```python
+        from piighost import ...
+        # your code here
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include the full traceback if applicable.
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: PIIGhost Version
+      placeholder: "e.g. 0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python Version
+      placeholder: "e.g. 3.12.3"
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other context, environment details, or screenshots.

piighost-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,37 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement to PIIGhost!
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or Motivation
+      description: Is your feature request related to a problem? Describe the context.
+      placeholder: "e.g. I'm always frustrated when I try to use a spaCy detector instead of GLiNER2..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: A clear description of what you'd like to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative approaches or workarounds you've considered.
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other context, examples, or references.

piighost-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this PR do? Why? -->
+
+## Changes
+
+<!-- Bullet list of the key changes -->
+
+## Checklist
+
+- [ ] `make lint` passes (ruff format, ruff check, pyrefly)
+- [ ] `uv run pytest` passes
+- [ ] New tests added for new functionality
+- [ ] Documentation updated if the public API changed
+- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
+
+## Related Issues
+
+<!-- Closes #123 -->

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

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  workflow_call:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint / Format / Type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-3.13-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-3.13-
+      # Sync full workspace (3.13 required by examples/graph) for lint
+      - run: uv sync --locked --dev --no-progress -q
+      - run: make lint
+
+  tests:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-${{ matrix.python-version }}-
+      - run: uv sync --locked --dev --no-progress -q
+      - run: uv run pytest

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

@@ -0,0 +1,34 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+        with:
+          enablement: true
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install zensical
+      - run: zensical build --clean
+      - run: zensical build -f zensical.fr.toml
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

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

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  ci:
+    name: CI Checks
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: Publish to PyPI & GitHub Release
+    runs-on: ubuntu-latest
+    needs: ci
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked --dev --no-progress -q
+      - run: uv build
+      - run: uv publish --verbose
+      - uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          generate_release_notes: true
+          files: |
+            dist/*.whl
+            dist/*.tar.gz

piighost-0.1.0/.gitignore

@@ -0,0 +1,175 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Virtual environments
+.venv/
+
+# IDE
+.vscode/
+*.swp
+*.swo
+# OS
+.DS_Store
+Thumbs.db
+

piighost-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

piighost-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-03-22
+
+### Features
+
+- **anonymizer**: 4-stage pipeline (Detect → Expand → Map → Replace) with protocol-based dependency injection
+- **detector**: `GlinerDetector` using GLiNER2 NER for entity detection
+- **occurrence-finder**: `RegexOccurrenceFinder` for word-boundary regex matching of all entity occurrences
+- **placeholder-factory**: `CounterPlaceholderFactory` for stable `<<LABEL_N>>` tags
+- **span-replacer**: `SpanReplacer` with reverse spans for reliable deanonymization
+- **pipeline**: `AnonymizationPipeline` with `PlaceholderStore` protocol for cross-session caching (SHA-256 keyed)
+- **middleware**: `PIIAnonymizationMiddleware` for LangChain/LangGraph — hooks on `abefore_model`, `aafter_model`, `awrap_tool_call`
+- **pipeline**: `deanonymize_value` for per-argument placeholder resolution
+- **examples**: LangGraph + FastAPI example with React frontend and Aegra integration

piighost-0.1.0/CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PIIGhost is a PII anonymization system for AI agent conversations. It transparently intercepts LLM interactions to detect, anonymize, and deanonymize sensitive entities (names, locations, etc.) using GLiNER2 NER, integrated via LangChain middleware into a LangGraph agent. Built on Aegra (self-hosted LangSmith alternative).
+
+## Development Commands
+
+```bash
+uv sync                      # Install dependencies
+uv run aegra dev             # Start dev server (graph + FastAPI on port 8000)
+make lint                    # Format (ruff), lint (ruff), type-check (pyrefly)
+uv run pytest                # Run all tests
+uv run pytest tests/test_anonymizer.py -k "test_name"  # Run a single test
+docker compose up postgres -d                           # PostgreSQL only
+docker compose up --build                               # Full stack (Postgres + API)
+```
+
+## Architecture
+
+### 4-Stage Anonymization Pipeline
+
+`Anonymizer` (`anonymizer/anonymizer.py`) orchestrates: **Detect → Expand → Map → Replace**
+
+1. **Detect**: `EntityDetector` protocol — `GlinerDetector` runs GLiNER2 NER to find entities
+2. **Expand**: `OccurrenceFinder` protocol — `RegexOccurrenceFinder` locates all occurrences via word-boundary regex
+3. **Map**: `PlaceholderFactory` protocol — `CounterPlaceholderFactory` assigns stable tags (`<<PERSON_1>>`)
+4. **Replace**: `SpanReplacer` applies character-position substitutions with reverse spans for deanonymization
+
+### Session Layer
+
+`AnonymizationPipeline` (`pipeline.py`) wraps the stateless `Anonymizer` with:
+- `PlaceholderStore` protocol — async persistent cache (SHA-256 keyed) for cross-session placeholder reuse
+- In-memory registry for fast bidirectional lookup within a session
+
+### Middleware Integration
+
+`PIIAnonymizationMiddleware` (`middleware.py`) extends LangChain's `AgentMiddleware`:
+- `abefore_model` — anonymizes all messages before the LLM sees them (NER on human messages, string-replace on AI/tool)
+- `aafter_model` — deanonymizes for user display
+- `awrap_tool_call` — deanonymizes tool args, executes tool, re-anonymizes result
+
+### Entry Points
+
+- **LangGraph agent**: `graph.py:graph` — agent with tools (`send_email`, `get_weather`) and PII middleware
+- **FastAPI app**: `app.py:app` — HTTP server with Keyshield API key auth and TTL sweeper background task
+- **Config**: `aegra.json` binds both together for `aegra dev`
+
+### Design Patterns
+
+All pipeline stages use **protocols** (structural subtyping) for dependency injection, making components swappable and testable. Tests use `FakeDetector` to avoid loading the real GLiNER2 model.
+
+## Conventions
+
+- **Commits**: Conventional Commits via Commitizen (`feat:`, `fix:`, `refactor:`, etc.)
+- **Type checking**: PyReFly (not mypy)
+- **Formatting/linting**: Ruff
+- **Package manager**: uv (not pip)
+- **Python**: 3.12+
+- **Data models**: Frozen dataclasses for immutability (`Entity`, `Placeholder`, `Span`, etc.)
+
+## Environment Setup
+
+Copy `.env.example` to `.env`. Key variables:
+- `OPENAI_API_KEY` (or `ANTHROPIC_API_KEY`) — required for LLM
+- `AEGRA_CONFIG=aegra.json` — mandatory
+- Database: PostgreSQL connection fields or `DATABASE_URL`
+- Observability: `OTEL_TARGETS` for Langfuse/Phoenix/OTLP tracing

piighost-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,65 @@
+# Code of Conduct
+
+## Our Commitment
+
+The PIIGhost team and community welcomes contributors worldwide who share our mission of making PII protection accessible and composable. We are committed to maintaining an inclusive, respectful environment for all participants.
+
+## Scope
+
+This code of conduct applies to all spaces managed by the PIIGhost project, including:
+- GitHub issues, pull requests, and discussions
+- Community events and meetups
+- Any other communication forums related to the project
+
+## Our Standards
+
+We ask all community members to:
+
+### Be Friendly and Patient
+
+Foster a welcoming atmosphere for everyone, regardless of experience level.
+
+### Be Welcoming
+
+To people of all backgrounds, identities, cultures, national origins, educational levels, sexual orientations, gender identities, ages, abilities, religions, and beliefs.
+
+### Be Considerate
+
+Our community spans the globe with varied primary languages. Your work and words affect others globally — be mindful of that.
+
+### Be Respectful
+
+Disagreements are natural and healthy. Disagreement does not justify poor behavior or personal attacks. Critique ideas, not people.
+
+### Choose Your Words Carefully
+
+We are a professional community. The following are not acceptable:
+- Violent threats or language
+- Discriminatory jokes or language
+- Sexual or violent content
+- Doxing or sharing private information
+- Personal insults
+- Unwelcome sexual attention
+- Harassment of any kind
+
+## Reporting Violations
+
+If you witness a violation of this code of conduct, please report it **privately** by opening a confidential report via [GitHub's private vulnerability reporting](https://github.com/Athroniaeth/piighost/security/advisories/new) or by contacting the maintainer directly.
+
+Include:
+- Description of the violation
+- Date and location (link, comment, etc.)
+- Any relevant evidence
+
+## Consequences
+
+Violations may result in:
+- Warning from maintainers
+- Temporary suspension from community participation
+- Permanent removal from the project
+
+The PIIGhost maintainers will review all reports and take appropriate action.
+
+---
+
+*Inspired by the Speak Up! project and the Contributor Covenant.*

piighost-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing to PIIGhost
+
+Thank you for your interest in contributing to PIIGhost! We welcome contributions from everyone.
+
+## Prerequisites
+
+- Python 3.12+
+- [`uv`](https://docs.astral.sh/uv/) package manager
+- Git and a GitHub account
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/piighost.git
+   cd piighost
+   ```
+3. **Add upstream remote** for syncing:
+   ```bash
+   git remote add upstream https://github.com/Athroniaeth/piighost.git
+   ```
+
+## Development Workflow
+
+### 1. Create a Feature Branch
+
+Always branch from `master`:
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 2. Install Dependencies
+
+```bash
+uv sync
+```
+
+### 3. Make Your Changes
+
+Follow the existing code style and patterns. Key conventions:
+- **Protocols** for every pipeline stage — keep components swappable
+- **Frozen dataclasses** for data models (`Entity`, `Placeholder`, `Span`, etc.)
+- **`FakeDetector`** in tests — never load the real GLiNER2 model in CI
+
+### 4. Quality Assurance
+
+Run all checks before submitting:
+
+```bash
+make lint         # Format (ruff), lint (ruff), type-check (pyrefly)
+uv run pytest     # Run tests
+```
+
+### 5. Commit Your Changes
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) via Commitizen:
+```bash
+cz commit
+```
+
+Follow the prompts to select commit type (`feat`, `fix`, `docs`, `refactor`, etc.).
+
+## Pull Request Guidelines
+
+1. **Target the `master` branch**
+2. **Ensure all checks pass**:
+   - `make lint` — no linting or type errors
+   - `uv run pytest` — all tests green
+3. **Add tests** for any new functionality
+4. **Update documentation** if the public API changes
+5. **Sync with upstream** if your branch diverged:
+   ```bash
+   git fetch upstream
+   git rebase upstream/master
+   git push --force-with-lease
+   ```
+
+### PR Checklist
+
+- [ ] Code follows project style guidelines
+- [ ] Tests pass locally (`make lint && uv run pytest`)
+- [ ] New tests added for new functionality
+- [ ] Documentation updated if needed
+- [ ] Synced with upstream master
+
+## Adding a New Pipeline Stage
+
+New detector, occurrence finder, or placeholder factory implementations must:
+- Implement the corresponding **protocol** (`EntityDetector`, `OccurrenceFinder`, `PlaceholderFactory`, `SpanValidator`)
+- Include tests that use the protocol interface (not the concrete class)
+- Not load heavy ML models in test code — use `FakeDetector` or equivalents
+
+## Questions?
+
+Open a [GitHub Discussion](https://github.com/Athroniaeth/piighost/discussions) or an issue. We're happy to help!
+
+---
+
+Thank you for contributing to PIIGhost!