Skip to content

README.md

Latest commit

 

History

History
70 lines (52 loc) · 2.47 KB

README.md

File metadata and controls

70 lines (52 loc) · 2.47 KB

cpex-plugins

Monorepo for managed CPEX plugins that are implemented in Rust and published as Python packages.

Layout

Managed plugins live under plugins/rust/python-package/<slug>/.

Current plugins:

  • rate_limiter
  • pii_filter

Each managed plugin must include:

  • pyproject.toml
  • Cargo.toml
  • Makefile
  • README.md
  • cpex_<slug>/__init__.py
  • cpex_<slug>/plugin-manifest.yaml

Python integration tests live under plugins/tests/<slug>/; Rust unit tests live in the plugin crate.

Rust crates are owned by the top-level workspace in Cargo.toml. Python package names follow cpex-<slug>, Python modules follow cpex_<slug>, plugin manifests must declare a top-level kind in module.object form, and pyproject.toml must publish the matching module:object reference under [project.entry-points."cpex.plugins"]. Release tags use the hyphenated slug form <slug-with-hyphens>-v<version>, for example rate-limiter-v0.0.2.

Creating a New Plugin

Use the plugin scaffold generator to create a new plugin with all required files and structure:

make plugin-scaffold

This interactive tool will:

  • Prompt for plugin name, description, author, and version
  • Let you select from 12 available hooks across 5 categories:
    • Prompt hooks: prompt_pre_fetch, prompt_post_fetch
    • Tool hooks: tool_pre_invoke, tool_post_invoke
    • Resource hooks: resource_pre_fetch, resource_post_fetch
    • Agent hooks: agent_pre_invoke, agent_post_invoke
    • HTTP hooks: http_pre_request, http_post_request, http_auth_resolve_user, http_auth_check_permission
  • Generate complete plugin structure with:
    • Rust source files (lib.rs, engine.rs, stub_gen.rs)
    • Python package files (__init__.py, plugin.py)
    • Build configuration (Cargo.toml, pyproject.toml, Makefile)
    • Documentation (README.md)
    • Comprehensive unit tests (Python and Rust)
    • Benchmark scaffolding

For non-interactive mode:

python3 tools/scaffold_plugin.py --non-interactive \
  --name my_plugin \
  --description "My plugin description" \
  --author "Your Name" \
  --hooks prompt_pre_fetch,tool_pre_invoke

Helper Commands

make plugins-list              # List all plugins
make plugins-validate          # Validate plugin structure
make plugin-test PLUGIN=rate_limiter  # Test specific plugin
make plugin-scaffold           # Create new plugin (interactive)

The catalog and validator used by CI live in tools/plugin_catalog.py.