python-pop 0.1.1

AI tooling for Python web applications.

python pop

python pop is an AI tooling package for Python frameworks. Package-authored AI assets live in a top-level .ai/ tree, install and update flows are agent-aware, project state is persisted in python-pop.json, and guidelines and skills are composed from detected framework and package modules.

Flask and Django are the first fully-authored frameworks in v1. FastAPI and Masonite remain detectable stubs so the package can grow without changing its shape.

Acknowledgements

python pop pulls heavy inspiration from Laravel Boost and its approach to AI-assisted framework tooling. Thank you to Taylor Otwell and the Laravel Boost team for building and openly sharing such a strong reference point for agent-aware developer tooling.

Please see THIRD_PARTY_NOTICES.md for more detailed attribution notes.

What it does

• Detects the project framework and relevant Python packages from pyproject.toml, requirements*.txt, lockfiles, and source markers.
• Composes managed guidelines from built-in and third-party modules.
• Syncs built-in and user-added skills into agent-specific skill directories.
• Installs MCP server configuration for supported agents.
• Persists selected agents, modules, and managed features in python-pop.json.
• Exposes a read-only stdio MCP server with project, Flask, and Django inspection tools.

Framework support

• Flask: rich authored guidelines, skills, version-aware module selection, and read-only MCP for routes, blueprints, CLI commands, config, and extensions.
• Django: rich authored guidelines, version-aware module selection, and read-only MCP for project inspection, routes, and management commands.
• FastAPI: detectable stub module with placeholder guidance and stub MCP tool.
• Masonite: detectable stub module with placeholder guidance and stub MCP tool.

Planned assets for future framework and dependency versions are bundled as placeholders and are excluded by default unless --include-planned is selected.

Getting started

Install Python Pop into a Python environment that is available from the project you want to configure:

python -m pip install python-pop

From the root of a Python web project, run the interactive installer:

python-pop install --project-root .

The installer detects the project framework, asks which AI agents to configure, writes managed guidelines and skills, configures MCP where supported, and persists the selected state in python-pop.json.

For a project-local, portable setup, use a dedicated virtual environment and run Python Pop from there:

python3 -m venv .venv-python-pop
.venv-python-pop/bin/python -m pip install python-pop
.venv-python-pop/bin/python -m python_pop install --project-root .

After install, inspect what Python Pop sees in the project:

python-pop inspect --project-root . --json

For automation or CI, pass explicit flags instead of using prompts:

python-pop install --project-root . --agent opencode --agent claude_code --guidelines --skills --mcp --no-interaction

Commands

python-pop inspect --project-root /path/to/project --json
python-pop install --project-root /path/to/project
python-pop update --project-root /path/to/project
python-pop add-skill your-org/your-python-pop-skills
python-pop mcp
python-pop execute-tool TOOL_NAME BASE64_JSON_ARGS

install and update write agent-specific outputs based on the selected or auto-detected agents. Managed state is stored in python-pop.json at the project root.

Releases

Release tooling uses an isolated environment and keeps build and twine out of runtime dependencies.

• Local release check: bash scripts/release-check.sh
• Release guide: docs/releasing.md
• Publish checklist: docs/publish-checklist.md
• Changelog: CHANGELOG.md

python pop follows Semantic Versioning. The first public release is 0.1.0, and breaking changes always require a major version increment.

Security boundaries

• Agent detection uses structured binary and filesystem checks instead of shell command execution.
• MCP project inspection is constrained to the configured project root when the server is installed through Python Pop.
• Remote GitHub skills are fetched from an immutable resolved ref and include a provenance sidecar file.
• Remote skill auditing rejects missing SKILL.md, unsafe paths, symlinks, binary content, and oversized payloads by default.
• --skip-audit exists as an explicit unsafe escape hatch for trusted local workflows.

Authored asset layout

The package authors its built-in AI content in a repo-root .ai/ tree and vendors that tree into the built wheel:

• .ai/foundation.md
• .ai/python-pop/...
• .ai/python/...
• .ai/flask/...
• .ai/django/...
• .ai/fastapi/...
• .ai/masonite/...

Skills live beside modules under paths like .ai/flask/skill/flask-development/SKILL.md.

Extensibility

Third-party packages can register framework or package modules through the python_pop.modules entry point group. External modules participate in the same detection and guideline composition flow as built-in modules when selected during install/update.

Optional Flask integration

The core package is framework-agnostic. If you want the Flask CLI group and lightweight extension helpers, install the Flask extra:

pip install "python-pop[flask]"

Then use either the standalone CLI or the Flask CLI group:

flask --app your_project python-pop inspect
flask --app your_project python-pop install

Optional application integration:

from python_pop.extension import PythonPop

pop = PythonPop()
pop.init_app(app)

Privacy

python pop is intended to be packaged and reused across projects. It should not ship private repo names, proprietary paths, or repo memory from any consuming application. Project-specific details belong in the consumer repository, for example under .ai/guidelines/repo_memory/..., not inside this package.