Metadata-Version: 2.4
Name: ai-project-blueprints
Version: 0.2.0
Summary: Validated, versioned project blueprint catalog for coding agents
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: jsonschema<5,>=4.25
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == "dev"
Requires-Dist: pyright<2,>=1.1.405; extra == "dev"
Requires-Dist: pytest<10,>=8.4; extra == "dev"
Requires-Dist: pytest-xdist<4,>=3.8; extra == "dev"
Requires-Dist: ruff<1,>=0.13; extra == "dev"
Requires-Dist: twine<7,>=6.2; extra == "dev"

# 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

```bash
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:

```python
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

```text
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.

```bash
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`](src/ai_project_blueprints/resources/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`](src/ai_project_blueprints/resources/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`](src/ai_project_blueprints/resources/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](src/ai_project_blueprints/resources/docs/stack-policy.md)
and [the React SPA stack policy](src/ai_project_blueprints/resources/docs/ui-stack-policy.md)
and [the feature-first architecture policy](src/ai_project_blueprints/resources/docs/code-architecture-policy.md)
and [the platform profile policy](src/ai_project_blueprints/resources/docs/platform-policy.md)
for selection rationale. The [package contract](src/ai_project_blueprints/resources/docs/package-contract.md)
and [release policy](src/ai_project_blueprints/resources/docs/release-policy.md)
define resource compatibility and GitLab.com/PyPI publication gates.
