Skip to content

AGENTS.md

Latest commit

 

History

History
170 lines (134 loc) · 5.94 KB

AGENTS.md

File metadata and controls

170 lines (134 loc) · 5.94 KB
Raw

Agent Instructions — Root

Monorepo containing a Python PII redaction library (privacy-filter) and agent framework integrations.

Repo Structure

.
privacy-filter/          # Core library — PII detection/redaction
├── src/privacy_filter/
│   ├── __init__.py      # Public API: get_classifier, redact_text, unredact_text, PiiStore
│   ├── pipeline.py      # HuggingFace transformers pipeline loader (lazy, thread-safe singleton)
│   ├── redact.py        # Entity merging, dedup, filtering, placeholder insertion
│   ├── unredact.py      # Placeholder → original value restoration
│   └── types.py         # PiiStore dataclass, ENTITY_SHORT_NAMES mapping
├── pyproject.toml       # Package: privacy-filter
├── README.md            # PyPI package documentation
└── uv.lock

nanobot-hook/            # NanoBot AgentHook integration
├── src/nanobot_hook/
│   ├── __init__.py      # Exports PrivacyFilterHook
│   └── hook.py          # AgentHook implementation
├── pyproject.toml       # Package: nanobot-privacy-filter-hook
└── README.md            # PyPI package documentation

openai-agents-hook/      # OpenAI Agents SDK guardrail integration
├── src/privacy_filter_openai/
│   ├── __init__.py      # Exports PiiInputGuardrail, PiiOutputGuardrail
│   └── guardrails.py    # Input/output guardrail implementations
├── pyproject.toml       # Package: openai-agents-privacy-filter
└── README.md            # PyPI package documentation

examples/
├── demo.py                   # Standalone demo (no external API needed)
├── server.py                 # End-to-end demo with OpenRouter LLM call
└── openai_agents_demo.py     # OpenAI Agents SDK with guardrails

Build & Release (Python Package)

This repo uses uv for dependency management and hatchling for building.

Three separate packages are published:

  • privacy-filter — Core PII library
  • nanobot-privacy-filter-hook — NanoBot AgentHook integration (depends on privacy-filter)
  • openai-agents-privacy-filter — OpenAI Agents SDK guardrails (depends on privacy-filter)

Publishing order matters: privacy-filter must be on PyPI before the integration packages can be built/published (because they declare privacy-filter as a dependency).

Prerequisites

Local Development

# Work on privacy-filter package
cd privacy-filter
uv sync                    # Install deps from uv.lock
uv run python -c "from privacy_filter import get_classifier; print('OK')"

Running Examples (from repo root)

Install packages as editable first:

uv pip install -e ./privacy-filter --system
uv pip install -e ./openai-agents-hook --system
uv pip install openai-agents --system

Then run with PYTHONPATH:

export PYTHONPATH="${PWD}/privacy-filter/src:${PWD}/openai-agents-hook/src"
export OPENROUTER_API_KEY=sk-or-v1-...

python examples/demo.py
python examples/server.py
python examples/openai_agents_demo.py

Building Wheels

# Build privacy-filter
cd privacy-filter
rm -rf dist/  # Clean old builds
uv build
# Outputs: dist/privacy_filter-*.whl and .tar.gz

# Build integration packages (privacy-filter must be installed first — use editable)
cd ../privacy-filter
uv pip install -e .

cd ../nanobot-hook
rm -rf dist/  # Clean old builds
uv build

cd ../openai-agents-hook
rm -rf dist/  # Clean old builds
uv build

Publishing to PyPI (Manual — No CI/CD)

No GitHub Actions workflows exist. Publish manually:

# 1. Publish privacy-filter FIRST
cd privacy-filter
uv build
uv publish dist/*
# Or with twine: twine upload dist/*

# 2. Wait for PyPI to propagate, then publish integration packages
cd ../nanobot-hook
uv build
uv publish dist/*

cd ../openai-agents-hook
uv build
uv publish dist/*

Important: If publishing integration packages fails because it can't find privacy-filter, wait a few minutes for PyPI index propagation or use --index-url with a local index.

Installing Locally (editable)

cd privacy-filter
uv pip install -e .        # Editable install

# Or from built wheel
uv pip install dist/privacy_filter-*.whl

Key Dependencies

  • privacy-filter: transformers>=4.40.0, torch>=2.0.0
  • nanobot-hook: depends on privacy-filter, optional nanobot-ai
  • openai-agents-hook: depends on privacy-filter, optional openai-agents
  • examples: requires openai, python-dotenv (install with --extra examples)

Important Implementation Notes

  1. Model download: First call to get_classifier() downloads ~50MB from HuggingFace (cached to ~/.cache/huggingface/ or cache_dir if specified)
  2. Thread-safety: get_classifier() uses double-checked locking for singleton pipeline
  3. Package path quirk: pyproject.toml uses packages = ["src/privacy_filter"] — this puts the package at root import privacy_filter, not src.privacy_filter
  4. Integration dependencies: All integration packages reference "privacy-filter" in pyproject.toml — for local dev, install privacy-filter first (editable) before working on nanobot-hook or openai-agents-hook

Testing Commands

# No formal test suite yet — verify with examples
cd privacy-filter
uv run python -c "
from privacy_filter import get_classifier, redact_text, unredact_text, PiiStore
store = PiiStore()
clf = get_classifier()
ents = clf('My email is test@example.com')
redacted = redact_text('My email is test@example.com', ents, store)
print('Redacted:', redacted)
print('Restored:', unredact_text(redacted, store))
"

Related Instructions