AI Project Blueprints

Versioned, inspectable starter packs for agents that create new projects. A pack combines a machine-readable manifest, agent instructions, dependency policies, and template assets. It is deliberately separate from the orchestrator: the orchestrator resolves and previews a pack, while this repository owns its content.

The current backend pack is python-api-fastapi@1.1.0; immutable 1.0.0 remains available. Its base profile uses FastAPI, Pydantic Settings, SQLAlchemy 2, Alembic, Ruff, Pyright, pytest and pytest-xdist. Exactly one database profile is selected: PostgreSQL by default or SQLite for bounded embedded/single-instance use. Testcontainers/PostgreSQL, Keycloak-compatible OIDC, Docker, and Kubernetes/Helm are explicit overlays. Version 1.1.0 adds feature-first vertical slices and lets agents choose the least elaborate internal structure for each use case.

The UI pack react-spa-vite@1.0.0 provides a browser-only React and strict TypeScript SPA with Vite, React Router, typed ESLint, Prettier, Vitest, and React Testing Library. Its feature-first structure keeps page-local journeys small and promotes reusable interactions or shared domain representations only when their boundaries are proven. Tailwind, OpenAPI client generation, TanStack Query, React Hook Form with Zod, OIDC/Keycloak, MSW, Playwright, runtime configuration, and non-root nginx delivery are explicit capabilities. The react-admin-api-spa service profile selects that recommended administrative UI combination without changing the minimal blueprint defaults.

Project-level operations are modeled separately through immutable platform packs. local-compose@1.0.0 provides a development dependency boundary; kubernetes-standard@1.0.0 provides provider-neutral Helm, Argo CD, Gateway API, OIDC, OpenTelemetry with an explicit telemetry backend, secret-management, backup, scheduler and event decisions. Stateful additions such as Keycloak, Velero, a self-hosted observability stack or a message broker stay explicit capabilities rather than silent service defaults.

Installation and API

pip install ai-project-blueprints==0.2.0
ai-project-blueprints list
ai-project-blueprints platform-list
ai-project-blueprints validate

Python consumers use ai_project_blueprints to discover and read resources. Access is backed by importlib.resources, so an installed wheel does not depend on a repository checkout:

from ai_project_blueprints import load_manifest, load_platform_manifest, read_text

manifest = load_manifest("python-api-fastapi", "1.1.0")
coder_instructions = read_text("blueprints/python-api-fastapi/1.1.0/instructions/coder.md")
platform = load_platform_manifest("kubernetes-standard", "1.0.0")

The API and CLI are inspect-only. They do not materialize or overwrite project files.

Layout

src/ai_project_blueprints/resources/  packaged catalogs, schemas, docs, examples, and packs
src/ai_project_blueprints/            public API, CLI, and trusted validation tooling
tests/         catalog invariant tests

Validate

Python 3.11+ is required for the catalog tooling.

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ai-project-blueprints validate
.venv/bin/ruff check .
.venv/bin/pyright
.venv/bin/pytest -n auto

The current release is a catalog contract and authored template pack. It does not yet include a materializer; consumers must preview an exact manifest version and preserve caller-owned files when they implement materialization.

Multi-service orchestration

catalog/service-workflows.json separates three provider-neutral concepts: a service_profile chooses blueprint defaults, an agent_bundle supplies ordered role instructions, and a workflow_bundle describes one bounded service workflow. The consumer-owned examples/python-multiservice-project.json shows backend services using different PostgreSQL/SQLite profiles and a React administrative UI using its own profile, instruction bundle, workflow bundle, and runtime-profile aliases under one workspace orchestrator.

catalog/platform-workflows.json adds environment-level platform profiles, agent bundles and bounded platform workflows. Workspace schema version 2 binds local to Compose and staging/production to Kubernetes while retaining per-role runtime aliases. Service workflows consume the resulting operational contracts but do not own shared cluster resources.

Concrete runtime aliases, models, providers, credentials and service-local instructions remain consumer-owned. The catalog only validates their safe logical bindings. Cross-service work is serialized and composed by the single host; a service workflow cannot start a nested orchestrator or independently claim the same checkout.

See the Python API stack policy and the React SPA stack policy and the feature-first architecture policy and the platform profile policy for selection rationale. The package contract and release policy define resource compatibility and GitLab.com/PyPI publication gates.