Metadata-Version: 2.4
Name: ai-project-blueprints
Version: 0.9.0
Summary: Validated, versioned project blueprint catalog for coding agents
Requires-Python: >=3.14
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 latest backend pack is `python-api-fastapi@1.3.0`; immutable `1.0.0`, `1.1.0` and `1.2.0`
remain 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.
Version `1.2.0` limits pack instructions to the FastAPI layout, selected stack,
overlays and concrete checks. Its application templates are unchanged. Existing
service profiles stay pinned to `1.1.0`; select `1.2.0` directly through its
manifest when adopting the separated instruction layout.

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.

The standalone `python-toolkit@2.0.0` pack provides a Python 3.14+ library, JSON
CLI and packaged instructions/resources. It starts with a standard-library runtime,
Ruff, strict Pyright, pytest, coverage, xdist, build and twine. A consumer-owned uv
lock makes development reproducible. It includes portable Python verification
scripts and an installed-wheel smoke outside the source tree. A single agent can
use it directly, without service/platform profiles. See the
[Python toolkit policy](src/ai_project_blueprints/resources/docs/python-toolkit-policy.md).

The instruction-only set
[`dotnet-project-guidance@2.7.0`](src/ai_project_blueprints/resources/instruction-sets/dotnet-project-guidance/2.7.0/agent.md)
provides portable C# vertical slices, compact compiler/analyzer-checked style,
isolated parallel tests and document-owned test references and shared optional runner adapters. It can
be adopted by existing services, workers, CLIs, libraries and fixture drivers.
Version2.1.0 adds SDK build checks, CleanupCode formatting and local InspectCode
after cohesive functionality blocks and at final task review before commit.
Version2.5.0 adds one canonical documentation tree with module ownership, separate
current procedures and dated evidence, and explicit migration checks. It is a
portable convention for new applications; existing projects keep their layout
until a scoped migration. Version2.4.0 moves test references into owner documents and uses shared evidence
adapters with semantic closure review. It retains standard SDK/JetBrains checks and review gaps
when retiring custom analyzers. Earlier versions remain immutable.
Version2.2.0 adds explicit module contracts, matching functional test projects
and bounded change context. Contract-first coordination supports repository-owned
modules and internal functional blocks when the consumer workflow permits
delegation; this guidance does not change the orchestrator's execution policy.
Versions1.0.0,2.0.0 and2.1.0 remain available unchanged.
It supplies guidance, without declaring an executable .NET starter or service
profile. Existing projects explicitly record the exact adopted version and
resource hashes; package updates do not rewrite their instructions.

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.

## Observability and typed access in 0.4.0

New immutable sets `dotnet-project-guidance@2.7.0` and
`python-project-guidance@1.2.0` apply Toolkit 0.7.2's general method. Typed models,
queries and projections move checks earlier; change tracking is a separate choice.
Actual provider/schema/concurrency verification remains necessary.
`python-api-fastapi@1.3.0` adds SQLAlchemy-specific rules without changing its
application templates. These sets also include the earlier boundary guidance.

`local-compose@1.1.0` and `kubernetes-standard@1.1.0` add a bounded persistent
metrics exporter queue and separate signal destinations. Their example budgets
are not production outage guarantees. Old resources and workflow pins remain
unchanged; choose these exact versions explicitly. See the
[release and migration](src/ai_project_blueprints/resources/docs/release-0.4.0.md)
and [verification scope](docs/plans/observability-typed-data.md).

## Container lifecycle guidance (0.5.0)

The opt-in instruction-only set
[`container-image-lifecycle@1.0.0`](src/ai_project_blueprints/resources/instruction-sets/container-image-lifecycle/1.0.0/agent.md)
describes replacing accepted developer images and releasing task-owned resources
that have no continuing purpose. Needed containers move to an owner inventory;
useful reports have a durable evidence location. It protects current/migration,
release/rollback and shared resources and defines verification before enabling
owner cleanup hooks. It selects no container platform and implements no cleaner.
Existing packs, sets and consumer selections remain unchanged. Distribution 0.5.0 includes this set; package publication and consumer adoption
remain separate steps. See [the execution record](docs/plans/container-image-lifecycle.md).

## Testing skills and scoped adoption (0.5.0)

New immutable sets `testing-foundations@1.0.0`, `dotnet-project-guidance@2.8.0`,
`python-project-guidance@1.3.0` and `typescript-project-guidance@1.0.0` supply
shared test design, conditional framework profiles and short testing skills.
Manifest v2 records exact dependencies and complete skill resources; v1 remains
compatible. Existing packs, versions and workflow pins are unchanged.

The [testing contract](src/ai_project_blueprints/resources/docs/testing-guidance-contract.md)
separates Blueprint engineering guidance from Toolkit evidence and consumer
commands. `resolve_instructions(adoption, target, task)` and
`instructions-for ADOPTION TARGET --task testing` inspect explicit service-root
bindings and return selected skill entrypoints/resource hashes. They install
nothing, execute no tests and activate no agents. See the
[mixed-stack example](src/ai_project_blueprints/resources/examples/testing-instruction-adoption.json).
Distribution 0.5.0 includes these changes; exact consumer adoption remains explicit. See [local verification](docs/plans/testing-guidance-and-skills.md).

## Installation and API

Distribution 0.9.0 provides
[`data-access-foundations@1.0.0`](src/ai_project_blueprints/resources/instruction-sets/data-access-foundations/1.0.0/agent.md),
`python-project-guidance@1.4.0`, `dotnet-project-guidance@2.9.0` and
[`sqlalchemy-persistence@1.0.0`](src/ai_project_blueprints/resources/instruction-sets/sqlalchemy-persistence/1.0.0/agent.md).
The shared foundation covers standard resource/transaction mechanisms and durable
outcomes for any language. Stack sets map those guarantees to Python, EF Core and
SQLAlchemy. Existing versions and consumer selections remain unchanged. See [exact adoption and scope](src/ai_project_blueprints/resources/docs/data-access-guidance-adoption.md).

Distribution 0.8.0 includes independent engineering inputs:
[`code-readability@1.0.0`](src/ai_project_blueprints/resources/instruction-sets/code-readability/1.0.0/agent.md),
[`performance-measurement@1.0.0`](src/ai_project_blueprints/resources/instruction-sets/performance-measurement/1.0.0/agent.md)
and [`dotnet-performance-measurement@1.0.0`](src/ai_project_blueprints/resources/instruction-sets/dotnet-performance-measurement/1.0.0/agent.md).
They cover cohesive decomposition, comparable CPU/memory measurements and .NET
counter/profiling boundaries without selecting the full .NET profile.
The .NET measurement set requires the exact general measurement set. These are
instruction-only inputs read through catalog/read APIs or reviewed local copies;
they declare no task skill for `instructions-for`. Existing bindings stay intact.
See [adoption and release scope](src/ai_project_blueprints/resources/docs/engineering-guidance-adoption.md).
The [0.8.0 publication receipt](docs/releases/0.8.0-verification.md) records verified
CI/PyPI artifacts and explicit ProSpace/Core adoption.

For explicit test-suite and fixture scopes, the independent
[`dotnet-testing-guidance@1.0.0`](src/ai_project_blueprints/resources/instruction-sets/dotnet-testing-guidance/1.0.0/agent.md)
provides testing guidance without full-project persistence/quality policies.
Select it as an alternative provider of `dotnet-testing`; preserve actual xUnit
v2/v3 or NUnit/MSTest project roles and owner commands.
[0.6.0 migration](src/ai_project_blueprints/resources/docs/release-0.6.0.md)
describes exact pins, complete receipts and host ownership checks.

```bash
pip install ai-project-blueprints==0.9.0
ai-project-blueprints list
ai-project-blueprints platform-list
ai-project-blueprints validate
```

Distribution 0.9.0 adds portable data access guidance and explicit stack mappings.
It preserves existing packs, instruction versions and consumer scopes.
See [0.9.0 migration](src/ai_project_blueprints/resources/docs/release-0.9.0.md).
[Release notes and migration](src/ai_project_blueprints/resources/docs/release-0.5.0.md)
explain the Python 3.14 requirement and explicit resource adoption. Inspect the
installed resources through the public CLI:

```bash
ai-project-blueprints manifest python-toolkit 2.0.0
ai-project-blueprints blueprint-smoke python-toolkit 2.0.0
ai-project-blueprints read catalog/instruction-sets.json
ai-project-blueprints read instruction-sets/dotnet-project-guidance/2.7.0/agent.md
```

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.2.0")
coder_instructions = read_text("blueprints/python-api-fastapi/1.2.0/instructions/coder.md")
platform = load_platform_manifest("kubernetes-standard", "1.0.0")
```

For instruction-only sets, use `load_catalog("instruction-sets")`, then
`read_json(entry["manifest"])` and `read_text()` for each declared instruction
relative to that manifest's directory. `resource_inventory("instruction-sets")`
lists their packaged files. The same reads work from an installed wheel.

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

## Python project guidance

[`python-project-guidance@1.0.0`](src/ai_project_blueprints/resources/instruction-sets/python-project-guidance/1.0.0/agent.md)
owns general Python architecture, types, dependencies, persistence, diagnostics
and verification. Its conditional worker guidance covers bounded I/O concurrency,
task/process ownership, cancellation, durable acceptance, retries and recovery.
The manifest declares all four instruction documents. The set selects no
framework, database, broker or service profile and creates no worker starter.

Adopt the set independently of a blueprint. To use it alongside FastAPI `1.2.0`,
record both exact manifests, load the set's declared instructions, then apply the
pack's stack-specific instructions. Neither selection implicitly loads the other.
These resources are included in distribution 0.3.0 and can be read through the
installed public API:

```python
from ai_project_blueprints import read_json, read_text

prefix = "instruction-sets/python-project-guidance/1.0.0"
manifest = read_json(f"{prefix}/manifest.json")
entrypoint = read_text(f"{prefix}/agent.md")
engineering = read_text(f"{prefix}/engineering.md")
worker = read_text(f"{prefix}/worker.md")
```

Use `ai-project-blueprints read instruction-sets/python-project-guidance/1.0.0/agent.md`
for JSON CLI output. Record the distribution version, set ID/version and complete
resource hashes. Existing `docs/python-engineering-policy.md` and
`docs/python-worker-policy.md` paths remain navigation pages; existing local copies
retain their provenance until explicitly migrated. See the
[package contract](src/ai_project_blueprints/resources/docs/package-contract.md#supplemental-engineering-instructions)
and [ownership and verification plan](docs/plans/python-guidance.md).

## Compatibility inspection

Совместимость можно проверить через `compatibility_matrix()`,
`resolve_combination()` и `golden_smoke()` либо команды
`compatibility-matrix` и `compatibility-smoke`. Матрица schema version 1
детерминированно выводится из canonical service/platform catalog и manifest,
поэтому неизвестный profile или capability отклоняется. Golden smoke собирает
объявленные файлы только в памяти, подставляет manifest examples/defaults,
сводит выбранные npm dependency records и прекращает работу при missing source
или target collision; consumer-файлы он не создаёт и не перезаписывает.

## 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.14+ is required for the catalog tooling. CI quality checks, builds and
publication use Python 3.14. Recreate older environments before upgrading to a
new package release with this minimum.

```bash
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ai-project-blueprints validate
.venv/bin/ruff check .
.venv/bin/pyright --pythonpath .venv/bin/python
.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.

Обычная проверка использует bounded `core` tier. Команды, которым действительно
нужны Docker, Helm, browser E2E или capability `testcontainers-postgresql`,
попадают в отдельный `heavyweight` tier и появляются только при выборе
соответствующей capability.
Opt-in CI с `BLUEPRINT_GENERATED_SMOKE=1` дополнительно материализует проекты во
временный каталог и запускает install, lint, typecheck, tests, build и SQLite
migration smoke. Временный каталог удаляется после проверки.

Standalone toolkit smoke resolves a fresh consumer lock and runs the generated
sequential/parallel gates, build and runtime-only installation:

```bash
python scripts/generated_toolkit_smoke.py --execute --python 3.14 --uv /path/to/uv
```

The same opt-in CI flag runs the catalog driver on Python 3.14 and checks the
generated 1.0.0 project on Python 3.11/3.14 and 2.0.0 on Python 3.14. These are
the immutable packs' consumer runtimes, selected with `--python` independently
of the catalog environment. The React smoke retains Node 24 and bootstraps a
Python 3.14 driver with pinned uv. Without `--execute`, the script only renders
into temporary storage and needs no uv or network. `blueprint_smoke()` provides
the in-memory variant through the package API.

## 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.

.NET guidance2.0.0 adds one project per application, cohesive shared modules,
EF Core persistence/migration bundles and copyable project-layout templates.
Immutable1.0.0 remains available. These instruction/example changes are included in distribution0.3.0.
Instruction-set versions are independent of the distribution version.

## TypeScript UI engineering — 0.7.0

[`typescript-project-guidance@1.1.0`](src/ai_project_blueprints/resources/instruction-sets/typescript-project-guidance/1.1.0/agent.md)
adds compiler/typed lint/format checkpoints, shared UI contracts and module-owned
behavior testing. TS1.0.0 and starter resources remain immutable. See
[scope and verification](docs/plans/typescript-ui-quality.md). This checkout change
does not publish a package or alter an existing consumer binding.

Distribution0.7.0 is published and verified. [Publication and exact-adoption receipt](docs/releases/0.7.0-verification.md)
records the protected source, exact CI/PyPI artifact hashes and fresh installation
checks. Consumer bindings choose new instruction versions explicitly.
