# Praxis AI Backend Config Contracts

> Use when changing or reviewing `AiBackendApiService`, governed audio transcription, `AI_BACKEND_CONFIG_STORE`, `AI_BACKEND_STORAGE_OPTIONS`, `AI_BACKEND_ENDPOINTS`, `API_URL` endpoint resolution, `/api/praxis/config/ai/**`, `/api/praxis/config/ai-context/**`, provider catalog/model/test/status endpoints, AI config snapshots, headers, ETag-adjacent identity, risk confirmation policy, manifest endpoints, or backend AI contract integration.

- Skill: `codexrodrigues/praxis-ai-backend-config-contracts` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-ai-backend-config-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-ai-backend-config-contracts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-ai-backend-config-contracts

---


# Praxis AI Backend Config Contracts

Use this skill for the Angular client boundary to Praxis Config AI services. The canonical provider execution and persisted AI configuration live behind Praxis Config endpoints, not inside browser UI or component libraries.

## Canonical Boundary

- `praxis-config-starter` is the canonical backend boundary for AI registry, provider/model execution, persisted AI config, templates, headers, and governed AI endpoints under `/api/praxis/config/**`.
- `AiBackendApiService` is the official Angular HTTP client for `/praxis/config/ai/**` and `/praxis/config/ai-context/**` materialized through configured base URLs.
- `PraxisAiService` and browser-provider helpers are legacy/local convenience surfaces. Do not route new governed authoring, provider catalog, status, streaming, or apply flows through browser-side provider execution.
- `AI_BACKEND_CONFIG_STORE` bridges host-owned AI config snapshots and save operations.
- `AI_BACKEND_STORAGE_OPTIONS` supplies tenant/env/user headers and optional local demo identity fallback.
- `AI_BACKEND_ENDPOINTS` may override AI and AI-context base URLs only when AI orchestration is served by a distinct gateway.
- `API_URL.default.baseUrl` is the preferred host-level source when endpoints share the platform API origin.

## Required Inventory

Inspect:

- `projects/praxis-ai/AGENTS.md`
- `projects/praxis-ai/README.md`
- `src/lib/core/services/ai-backend-api.service.ts`
- `src/lib/core/services/ai-backend-api.service.spec.ts`
- `src/lib/core/services/governed-audio-transcription.service.ts` and the assistant shell voice flow when transcription is in scope
- `src/lib/core/services/praxis-ai.service.ts` when a change risks browser-side provider execution or legacy fallback behavior
- `src/lib/core/contracts/ai-contract.generated.ts`
- `praxis-config-starter/docs/ai/contracts/praxis-ai-api-contract-v1.1.openapi.yaml`
- `praxis-config-starter/docs/ai/contracts/README.md`
- `praxis-config-starter/tools/contracts/generate-ai-contract-bindings.js`
- `src/lib/core/models/ai-models.ts`
- `src/public-api.ts`
- host provider setup for `API_URL` and `AI_BACKEND_*` tokens
- relevant `praxis-config-starter` AI registry/config endpoint contracts when backend behavior changes
- `praxis-config-starter` `AiAudioTranscriptionController`, `AiProviderManagementService`, `AiProvider`, transcription DTO/request, controller test, and AI contract docs when governed transcription changes

Use `praxis-ai-authoring-manifests` for component manifest endpoints and edit-plan shape. Use `praxis-ai-turn-orchestration-transport` for turn stream conversion.

When backend contract behavior is in scope, load the relevant config-starter skill before changing Angular client DTOs or endpoint fallbacks:

- `praxis-config-runtime-persistence` for `/api/praxis/config/ui`, headers, ETag, and `/api/praxis/runtime/**`.
- `praxis-config-ai-registry-manifests` for `ai_registry`, templates, component definitions, manifest endpoints, validators, and compilers.
- `praxis-config-api-metadata-grounding` for `api_metadata`, AI context, RAG, Project Knowledge, and resource candidates.
- `praxis-config-agentic-authoring-streaming` for `/api/praxis/config/ai/**`, turn streams, quick replies, diagnostics, start/probe/replay/cancel, and terminal events.
- `praxis-config-domain-decisions` for domain rules, domain knowledge, publications, materializations, and governed decision diagnostics.

## Endpoint Rules

- Resolve AI base URL in this order: explicit `AI_BACKEND_ENDPOINTS.aiBaseUrl`, derived `API_URL.default.baseUrl + praxis/config/ai`, fallback `/api/praxis/config/ai`.
- Resolve AI context base URL in this order: explicit `AI_BACKEND_ENDPOINTS.aiContextBaseUrl`, derived `API_URL.default.baseUrl + praxis/config/ai-context`, fallback `/api/praxis/config/ai-context`.
- Do not hardcode external provider URLs in `@praxisui/ai`. Provider catalog, model listing, status, test calls, suggestions, patches, stream start/connect/cancel, observation feedback, and authoring manifest operations go through the Praxis Config boundary.
- `POST /api/praxis/config/ai/transcriptions` is the canonical short-audio transcription boundary. Send multipart `audio` plus optional `language` through the resolved AI base URL, preserve credentials and tenant/user/environment headers, and accept only the safe transcription response. Do not derive a provider endpoint, key, model, or fallback in Angular.
- `GET /api/praxis/config/ai/transcriptions/capabilities` returns only `{ available: boolean }` with `Cache-Control: no-store`. Use `AiBackendApiService.getAudioTranscriptionCapabilities()` with the same resolved AI base URL, scoped headers and credentials before requesting microphone access. Accept only explicit `true`; do not infer availability from chat status, catalog provider names, browser recording support or frontend credentials.
- Availability reports local provider support and effective credential configuration; it makes no provider call and does not certify key validity, connectivity, quota or extra permissions. Configuration lookup failures must yield `false` without configuration details; distinguish absent configuration from unavailable storage or decryption. Host admission may reject session, scope or stale context before readiness runs. A missing or failing endpoint must not trigger browser-speech or direct-provider fallback.
- A transcription response is editable user-input material, not an assistant result. It must not start a turn, resolve intent, auto-submit, mutate history, authorize preview/apply, or become trusted grounding merely because Config returned provider/model metadata.
- Preserve generated contract version and schema hash headers for patch/orchestrator contracts.
- Treat `praxis-config-starter/docs/ai/contracts/praxis-ai-api-contract-v1.1.openapi.yaml` as the canonical AI HTTP/SSE contract source. Do not hand-edit `ai-contract.generated.ts` or Java contract constants; update the OpenAPI source, run `node tools/contracts/generate-ai-contract-bindings.js` from `praxis-config-starter`, and commit the generated Java/TypeScript outputs together.
- Preserve tenant/user/env headers from `AI_BACKEND_STORAGE_OPTIONS`. Local identity fallback is for demos/local hosts and must be explicit.
- Stream connections must respect `withCredentials`, access tokens, probe endpoints, and explicit headers. Fetch fallback is required when EventSource cannot carry needed headers.
- Stream connection failures are classified as `unsupported`, `http_status`, `transport`, `parse`, or `schema`. Preserve those categories so callers can distinguish host capability, auth/probe failure, transport loss, malformed payload, and contract drift.
- Risk confirmation policy is contract-owned. Frontend can display and require confirmation, but should not downgrade risk locally.

## Client Invariants

- `AI_BACKEND_ENDPOINTS` is an explicit gateway override, not a second contract family. If absent, derive both bases from the shared `API_URL.default.baseUrl`; use the `/api/...` fallbacks only when neither host configuration exists.
- Tenant, user, and environment headers scope the request. Conversation/session and client turn IDs identify an interaction; do not substitute one for the other or move identity into ad hoc query parameters.
- Local demo identity is permitted only through the explicit storage option. An empty or failing header factory must not silently inject demo credentials in a real host.
- Normalize only the contract-supported UUID identities sent to backend turn endpoints. Omit noncanonical UI-only IDs instead of manufacturing server identity.
- Send contract version and schema-hash headers for patch/start requests after normalizing them. A generated-contract mismatch, malformed SSE envelope, incompatible event schema version, failed probe, or unauthorized stream is a classified transport/contract failure, never a successful assistant result.
- Preserve credentials and the same authorization scope for start, probe, connect, cancel, feedback, and replay. Signed access tokens may be carried only where the canonical stream contract allows them, and must travel consistently in probe/stream/cancel URLs or headers according to that contract.
- Treat `streamAuthMode` and `streamAccessToken` from the generated start response as backend-issued transport authority for that stream only. The Angular client may forward the returned token to probe/connect/cancel exactly as the contract permits, but must not mint tokens, cache them across turns, reuse them across streams, derive them from session/client turn IDs, or downgrade required host headers into query parameters.
- Fetch SSE is the transport fallback when EventSource is unavailable or required host headers cannot be carried; it does not justify a new endpoint, unauthenticated stream, or different envelope parser.
- Agentic authoring `intent.resolved` is replay-safe and non-terminal. UI clients must keep processing until `result`, `error`, or `cancelled`; do not treat early user-facing understanding as completion.
- Decision diagnostics such as `semanticDecisionReviewGroundedByPreview`, schema verification, lexical fallback flags, and tool-loop traces are audit evidence. They may explain why a result needs review or is unsafe, but cannot grant `canApply`, create an apply payload, or override backend risk confirmation policy in the browser.
- Feedback is write-only triage evidence. It cannot mutate config, risk policy, semantic decision, preview, or apply state.
- `getHeaderContext()` exposes request scope for display, diagnostics, and host wiring checks only. Missing
  tenant/user/env headers must surface as integration scope evidence, not as permission to fabricate demo identity,
  reuse a UI session id, or move tenant/user/environment into turn ids, prompts, query params, local history, or
  semantic decisions.
- Observation feedback responses (`feedbackId`, `observationId`, `rating`, reason/comment echoes) are audit/triage
  acknowledgements. They must not reopen a turn, change assistant history content, revise a quick reply, update
  `canApply`, or become grounding evidence for a later request unless a separate backend contract explicitly returns
  governed remediation context.

Provider catalog/status/test/transcription responses are operational projections
from Config Starter. Angular may present sanitized provider/model/status/failure
information and append returned transcript text for user review, but must not
own routing, retry, pricing, key storage, transcription policy, or cost
attribution. Use `praxis-config-ai-provider-operations` when those contracts
change.

## Inventory Before New Contracts

Before adding a token, endpoint, DTO, or exported type, answer: what does the platform already know but this client, host, or UX is not materializing correctly?

Classify each gap:

- `ja-suportado-so-ux`: endpoint or token already exists; only host wiring or UX needs correction.
- `ja-suportado-mal-nomeado-ou-mal-materializado`: existing field/endpoint is present but projected poorly.
- `suportado-parcialmente`: backend has evidence but client normalization or generated contract is incomplete.
- `lacuna-real-de-contrato`: backend cannot provide the required governed behavior without a new canonical contract.

Only `lacuna-real-de-contrato` justifies a new public contract. Identify backend owner, consumers, generated artifacts, docs/examples, and focal validation.

## Validation

Use focused checks:

- client endpoints, headers, base URL resolution, multipart transcription, streams: `ai-backend-api.service.spec.ts`
- turn stream behavior: `agentic-authoring-turn-client.service.spec.ts`
- generated AI contracts: contract generation/validator specs when schema changes
- public exports: build `praxis-ai` and a direct consumer when `public-api.ts` changes
- backend endpoint behavior: focused `praxis-config-starter` tests when backend contracts change

For governed transcription, prove scoped multipart encoding, `withCredentials`,
scoped capability discovery, fail-closed readiness before microphone permission,
safe response handling, no automatic turn submission, capture cancellation and
track cleanup. Run the Config controller test and the provider management/
provider adapter tests applicable to the selected implementation; if the latter
do not exist, report that test gap explicitly rather than using an Angular HTTP
mock as provider proof.

For AI HTTP/SSE contract source, generated binding, schema hash, or retro-compatibility changes, use the backend contract gate:

```sh
mvn "-Dtest=AiApiContractOpenApiTest,AiContractSpecConsistencyTest,AiContractV11RetroCompatibilityTest" test
```

Then run the Angular generated-contract spec:

```sh
npm exec -- ng test praxis-ai --watch=false --progress=false \
  --include='projects/praxis-ai/src/lib/core/contracts/ai-contract.generated.spec.ts' \
  --include='projects/praxis-ai/src/lib/core/services/ai-backend-api.service.spec.ts'
```

State explicitly when no `praxis-config-starter`, public docs, examples, registry, or generated contract artifacts need updates.

Exercise endpoint precedence, absent versus explicit local identity, normalized turn identity, contract headers, typed manifest calls, credentials, signed-token cancel/probe, fetch fallback, invalid envelope/schema version, forbidden probe status, and write-only feedback. For a backend/public change, additionally prove the config-starter owner and downstream quickstart scope; do not present Angular mocks as HTTP/SSE authorization proof.

For corporate transcription, inspect the host's existing session-context admission and version stamp, not just `AiPrincipalContextResolver` mocks. Quickstart's enterprise composition must bind the resolver to revalidated SESSION/membership, reject stale `X-Praxis-Context-Version` and conflicting scope, and sanitize source failures. Preserve the UI writer's capability checks when sharing admission code. Inventory every caller affected by a host resolver override. Do not replace session authority with default tenants or caller headers.

Host transport must classify only the intended configured-origin audio routes as corporate, strip demo authorization, preserve canonical context headers and use session credentials/CSRF according to host policy. Check actual CSRF matchers: enabling the filter chain in a test does not prove token enforcement on an exempt endpoint. Never describe a test against an older installed backend as proof of a newly added endpoint.

