ai-capability-framework 1.0.0-rc.3 → 1.0.0

package/docs/getting-started/anthropic-quickstart.md

@@ -0,0 +1,61 @@
+# Anthropic Quickstart
+
+Use this guide when your host app wants Claude Messages tools backed by AICF. The
+default path uses mock clients and descriptor checks. Live calls are explicitly opt-in.
+
+## Install
+
+Core AICF does not require the Anthropic SDK:
+
+```bash
+npm install ai-capability-framework
+```
+
+Only apps that construct a default Claude client need the optional SDK:
+
+```bash
+npm install @anthropic-ai/sdk
+```
+
+Provider imports stay isolated:
+
+```ts
+import { runAnthropicMessages } from "ai-capability-framework/providers/anthropic";
+```
+
+## Mock-Tested Flow
+
+Run the Anthropic mock runtime tests:
+
+```bash
+npm run test:anthropic:mock
+```
+
+Expected output excerpt:
+
+```text
+Test Files ... passed
+```
+
+The Anthropic adapter converts routed AICF read/prepare capabilities into Claude tool
+definitions and maps `tool_use` blocks back through AICF bindings.
+
+## Live Opt-In
+
+Live tests are skipped unless you explicitly opt in:
+
+```bash
+RUN_LIVE_ANTHROPIC=1 ANTHROPIC_API_KEY=... AICF_ANTHROPIC_MODEL=claude-sonnet-4-5 \
+  npm run test:anthropic:live
+```
+
+For live evals:
+
+```bash
+RUN_REAL_AICF_LIVE_EVALS=1 ANTHROPIC_API_KEY=... \
+  node dist/cli.js eval-live examples --cases cases.json --provider anthropic --model claude-sonnet-4-5
+```
+
+AICF remains the validation, policy, lifecycle, approval, idempotency, and model-safe
+envelope authority. Anthropic tool definitions are an adapter projection, not trusted
+execution.

package/docs/getting-started/concepts.md

@@ -1,22 +1,21 @@
 # Concepts
 
-AICF is not an agent framework. It is a governed capability layer for
-AI-accessible application functionality.
+AICF is not an agent framework. It is a governed capability layer for AI-accessible
+application functionality.
 
 Models propose; applications validate, authorize, execute, and audit.
 
 Core concepts:
 
 - A capability is a typed, versioned operation your app may expose to AI.
-- A manifest describes the capability, schema, risk, lifecycle, policy, and
-  eval coverage.
+- A manifest describes the capability, schema, risk, lifecycle, policy, and eval
+  coverage.
 - A registry is the validated set of capability, entity, and eval manifests.
-- A routed slice is the small set of read/prepare capabilities exposed for one
-  request.
+- A routed slice is the small set of read/prepare capabilities exposed for one request.
 - Provider adapters turn a slice into provider-specific tool descriptors.
-- Runtime validation maps model tool calls back to capability IDs and validates
-  args before any handler runs.
-- Commit stays host-controlled through prepared actions, approvals,
-  idempotency, audit records, and optional controls.
+- Runtime validation maps model tool calls back to capability IDs and validates args
+  before any handler runs.
+- Commit stays host-controlled through prepared actions, approvals, idempotency, audit
+  records, and optional controls.
 
 See the [Glossary](../glossary.md) for short definitions.

package/docs/getting-started/gemini-quickstart.md

@@ -0,0 +1,62 @@
+# Gemini Quickstart
+
+Use this guide when your host app wants Google Gemini GenerateContent function calling
+backed by AICF. The default path uses mock clients and descriptor checks. Live calls are
+explicitly opt-in.
+
+## Install
+
+Core AICF does not require the Google GenAI SDK:
+
+```bash
+npm install ai-capability-framework
+```
+
+Only apps that construct a default Gemini client need the optional SDK:
+
+```bash
+npm install @google/genai
+```
+
+Provider imports stay isolated:
+
+```ts
+import { runGeminiGenerateContent } from "ai-capability-framework/providers/gemini";
+```
+
+## Mock-Tested Flow
+
+Run the Gemini mock runtime tests:
+
+```bash
+npm run test:gemini:mock
+```
+
+Expected output excerpt:
+
+```text
+Test Files ... passed
+```
+
+The Gemini adapter converts routed AICF read/prepare capabilities into function
+declarations and maps `functionCall` parts back through AICF bindings.
+
+## Live Opt-In
+
+Live tests are skipped unless you explicitly opt in:
+
+```bash
+RUN_LIVE_GEMINI=1 GEMINI_API_KEY=... AICF_GEMINI_MODEL=gemini-2.5-flash \
+  npm run test:gemini:live
+```
+
+For live evals:
+
+```bash
+RUN_REAL_AICF_LIVE_EVALS=1 GEMINI_API_KEY=... \
+  node dist/cli.js eval-live examples --cases cases.json --provider gemini --model gemini-2.5-flash
+```
+
+AICF remains the validation, policy, lifecycle, approval, idempotency, and model-safe
+envelope authority. Gemini function declarations are an adapter projection, not the
+source of truth.

package/docs/getting-started/installation.md

@@ -14,8 +14,8 @@ npm run build
 npm run validate
 ```
 
-The default examples use fake data and do not call live model providers. Live
-provider tests are opt-in and require explicit environment variables documented
-in the provider guides.
+The default examples use fake data and do not call live model providers. Live provider
+tests are opt-in and require explicit environment variables documented in the provider
+guides.
 
 Next: [Quickstart](quickstart.md).

package/docs/getting-started/openai-quickstart.md

@@ -0,0 +1,61 @@
+# OpenAI Quickstart
+
+Use this guide when your host app wants OpenAI Responses tools backed by AICF. The
+default commands are mock or descriptor checks. Live calls are opt-in.
+
+## Install
+
+Core AICF does not require the OpenAI SDK:
+
+```bash
+npm install ai-capability-framework
+```
+
+Only apps that create a default OpenAI client need the optional SDK:
+
+```bash
+npm install openai
+```
+
+Root and runtime imports remain lightweight:
+
+```ts
+import { loadRegistryFromPath } from "ai-capability-framework";
+import { runOpenAIResponses } from "ai-capability-framework/openai";
+```
+
+## Mock-Tested Flow
+
+Run the existing mock runtime tests:
+
+```bash
+npm run test:openai:mock
+```
+
+Expected output excerpt:
+
+```text
+Test Files ... passed
+```
+
+The OpenAI runtime exports only routed read/prepare tools. Commit tools remain
+host-controlled through AICF action lifecycle APIs.
+
+## Live Opt-In
+
+Live tests are skipped unless you explicitly opt in:
+
+```bash
+RUN_REAL_OPENAI=1 OPENAI_API_KEY=... AICF_OPENAI_MODEL=gpt-4.1-mini npm run test:openai:live
+```
+
+For live evals, the CLI has its own explicit guard:
+
+```bash
+RUN_REAL_AICF_LIVE_EVALS=1 OPENAI_API_KEY=... \
+  node dist/cli.js eval-live examples --cases cases.json --provider openai --model gpt-4.1-mini
+```
+
+AICF remains the validation, policy, lifecycle, approval, idempotency, and model-safe
+envelope authority. OpenAI tool schemas are an adapter projection, not the source of
+truth.

package/docs/getting-started/provider-neutral-quickstart.md

@@ -0,0 +1,106 @@
+# Provider-Neutral Quickstart
+
+Use this path first if you want to understand AICF without choosing a model provider. It
+uses the public support/refund examples and does not require API keys, provider SDKs,
+live calls, or credentials.
+
+## What You Will Prove
+
+- Capability manifests can describe app functionality without provider-specific schemas.
+- AICF can validate the registry and inspect the capability set.
+- Deterministic decisions and evals run without calling a model.
+- Provider adapters are optional layers over the same AICF contracts.
+
+## 1. Install And Build
+
+```bash
+npm ci
+npm run build
+```
+
+Expected output excerpt:
+
+```text
+added ... packages
+tsc -p tsconfig.json
+```
+
+## 2. Inspect A Capability Manifest
+
+Open `examples/support/capabilities/support.ticket.get.yaml`. It defines a read-only
+support ticket capability with input/output schemas, permissions, risk, status, and
+lifecycle metadata.
+
+The important point is that the manifest is provider-neutral. It is not an OpenAI,
+Anthropic, Gemini, MCP, LangChain, or AI SDK schema.
+
+## 3. Validate Public Examples
+
+```bash
+npm run validate
+```
+
+Expected output excerpt:
+
+```text
+Validated 16 manifest(s) and 18 fixture(s).
+```
+
+## 4. Inspect The Registry
+
+```bash
+node dist/cli.js inspect examples
+```
+
+Expected output excerpt:
+
+```text
+Capabilities:
+- support.ticket.get
+- support.refund.prepare_case
+- support.refund.commit_case
+```
+
+## 5. Run A Deterministic Decision
+
+```bash
+node dist/cli.js decide examples --request examples/support/decisions/support.ticket.get.select.json
+```
+
+Expected output excerpt:
+
+```text
+allowed: true
+capability: support.ticket.get
+```
+
+This proves the policy/selection path without a model. The request uses a synthetic
+user, tenant, permissions, and arguments.
+
+## 6. Run Deterministic Evals
+
+```bash
+node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
+```
+
+Expected output excerpt:
+
+```text
+Eval suite passed
+```
+
+The eval runner checks expected selected capabilities, tool calls, arguments,
+approval-required behavior, and no-commit boundaries from public fixtures. It does not
+call a provider.
+
+## 7. Export Provider Descriptors Later
+
+When you are ready to connect a provider, choose a runtime from
+[Choose a Runtime](../providers/choose-a-runtime.md). The provider adapter will export a
+routed AICF capability slice, but AICF validation and policy remain the authority.
+
+Useful next steps:
+
+- [OpenAI quickstart](openai-quickstart.md)
+- [Anthropic quickstart](anthropic-quickstart.md)
+- [Gemini quickstart](gemini-quickstart.md)

package/docs/getting-started/quickstart.md

@@ -25,8 +25,8 @@ What this proves:
 
 - manifests and fixtures validate;
 - read/prepare tools can be exported without exposing commit tools;
-- the runtime can read, prepare, require approval, and commit through host
-  lifecycle APIs;
+- the runtime can read, prepare, require approval, and commit through host lifecycle
+  APIs;
 - evals prove expected behavior without calling a model.
 
 Full command explanations are in [Start here](../start-here.md).

package/docs/getting-started.md

@@ -1,29 +1,31 @@
 # Getting Started
 
 If you are new to AICF, start with [Start here](start-here.md). It uses the
-support/refund example and includes exact commands plus expected output
-excerpts.
+support/refund example and includes exact commands plus expected output excerpts.
 
-Use this page as a short checklist when you are ready to model your own
-capability.
+Use this page as a short checklist when you are ready to model your own capability.
 
 ## Checklist
 
 1. Read the [glossary](glossary.md) so the main terms are clear.
-2. Run the public support/refund walkthrough in [Start here](start-here.md).
-3. Read the concrete [OpenAI walkthrough](openai-walkthrough.md), even if your
-   first provider is not OpenAI. It is the baseline mental model for all
-   provider adapters.
-4. Pick one application behavior the model may request.
-5. Write a capability manifest with strict input and output schemas.
-6. Mark risk, side effects, authorization, lifecycle, and approval rules
-   explicitly.
-7. Add synthetic eval cases for selection, arguments, refusal, approval, and
-   no-commit boundaries.
-8. Run `npm run validate`.
-9. Export the relevant provider tools from a routed context.
-10. Keep real auth, side effects, approvals, durable storage, and audit in your
-    host application.
+2. Run the no-key
+   [provider-neutral quickstart](getting-started/provider-neutral-quickstart.md).
+3. Run the public support/refund walkthrough in [Start here](start-here.md).
+4. Choose a provider/runtime path with
+   [Choose a Runtime](providers/choose-a-runtime.md).
+5. Use the provider quickstart that matches your host app:
+   [OpenAI](getting-started/openai-quickstart.md),
+   [Anthropic](getting-started/anthropic-quickstart.md), or
+   [Gemini](getting-started/gemini-quickstart.md).
+6. Pick one application behavior the model may request.
+7. Write a capability manifest with strict input and output schemas.
+8. Mark risk, side effects, authorization, lifecycle, and approval rules explicitly.
+9. Add synthetic eval cases for selection, arguments, refusal, approval, and no-commit
+   boundaries.
+10. Run `npm run validate`.
+11. Export the relevant provider tools from a routed context.
+12. Keep real auth, side effects, approvals, durable storage, and audit in your host
+    application.
 
 ## Useful Commands
 
@@ -31,9 +33,10 @@ capability.
 npm run validate
 npm run build
 node dist/cli.js inspect examples
+node dist/cli.js decide examples --request examples/support/decisions/support.ticket.get.select.json
 node dist/cli.js openai-tools examples --context examples/support/openai/context.support_agent.json
 node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
 ```
 
-AICF validation and evals are deterministic. They do not call models, execute
-side effects, or require provider credentials.
+AICF validation and evals are deterministic. They do not call models, execute side
+effects, or require provider credentials.

package/docs/glossary.md

@@ -1,71 +1,54 @@
 # Glossary
 
-Capability:
-An application action or read operation that a model may request. A capability
-has an ID, input/output schemas, risk metadata, lifecycle rules, policy gates,
-and eval links.
+Capability: An application action or read operation that a model may request. A
+capability has an ID, input/output schemas, risk metadata, lifecycle rules, policy
+gates, and eval links.
 
-Manifest:
-A public YAML or JSON file that describes an AICF contract. Capability, entity,
-eval, decision, context, and result manifests are validated before use.
+Manifest: A public YAML or JSON file that describes an AICF contract. Capability,
+entity, eval, decision, context, and result manifests are validated before use.
 
-Registry:
-The validated in-memory collection of manifests. AICF uses the registry for
+Registry: The validated in-memory collection of manifests. AICF uses the registry for
 routing, provider export, decisions, execution checks, and eval scoring.
 
-Slice:
-A small filtered set of capabilities for one request or workflow. Slices keep
-the model tool list focused and exclude unsafe or irrelevant capabilities.
+Slice: A small filtered set of capabilities for one request or workflow. Slices keep the
+model tool list focused and exclude unsafe or irrelevant capabilities.
 
-Adapter:
-Code that converts AICF capabilities into another provider or framework tool
+Adapter: Code that converts AICF capabilities into another provider or framework tool
 shape. Descriptor adapters do not call models or execute handlers.
 
-Provider Runtime:
-An optional bounded model/tool loop for a specific provider, such as OpenAI,
-Anthropic, or Gemini. It still routes through AICF validation, policy, and
+Provider Runtime: An optional bounded model/tool loop for a specific provider, such as
+OpenAI, Anthropic, or Gemini. It still routes through AICF validation, policy, and
 runtime envelopes.
 
-Handler:
-Host application code registered for a capability. Handlers read data or
+Handler: Host application code registered for a capability. Handlers read data or
 prepare actions; commit handlers are invoked only by the lifecycle manager.
 
-Executor:
-The runtime component that validates a read or prepare request, checks policy,
-calls the registered handler, validates output, and returns a model-safe
-envelope.
+Executor: The runtime component that validates a read or prepare request, checks policy,
+calls the registered handler, validates output, and returns a model-safe envelope.
 
-Lifecycle Manager:
-The runtime component that prepares actions, records approvals, checks
-idempotency, commits stored prepared actions, and emits audit summaries.
+Lifecycle Manager: The runtime component that prepares actions, records approvals,
+checks idempotency, commits stored prepared actions, and emits audit summaries.
 
-Prepared Action:
-A stored action preview created before side effects happen. It contains the
-validated arguments and summary needed for approval and later commit.
+Prepared Action: A stored action preview created before side effects happen. It contains
+the validated arguments and summary needed for approval and later commit.
 
-Approval:
-A host-controlled decision that allows or rejects a prepared action. AICF can
+Approval: A host-controlled decision that allows or rejects a prepared action. AICF can
 record and check approvals, but the host owns the approval UI and real authority.
 
-Idempotency:
-A key-based protection against duplicate commits. It lets the lifecycle manager
-return an existing result instead of repeating a side effect.
+Idempotency: A key-based protection against duplicate commits. It lets the lifecycle
+manager return an existing result instead of repeating a side effect.
 
-Envelope:
-A JSON-serializable result wrapper returned to the model or host. Envelopes make
-success, validation errors, denials, approval-required pauses, unavailable
+Envelope: A JSON-serializable result wrapper returned to the model or host. Envelopes
+make success, validation errors, denials, approval-required pauses, unavailable
 handlers, and failures explicit.
 
-Eval:
-A deterministic test case that describes expected model/tool behavior. AICF
-evals do not call models; they score candidate result fixtures.
+Eval: A deterministic test case that describes expected model/tool behavior. AICF evals
+do not call models; they score candidate result fixtures.
 
-Candidate Result:
-A public-safe summary of observed behavior for an eval case. It records selected
-capabilities, tool calls, policy decisions, action state, refusal, and response
-text without raw provider payloads.
+Candidate Result: A public-safe summary of observed behavior for an eval case. It
+records selected capabilities, tool calls, policy decisions, action state, refusal, and
+response text without raw provider payloads.
 
-Conformance:
-A descriptor/mock check that one routed capability slice maps consistently
-across providers and frameworks. It verifies names, bindings, schemas, safe
-errors, and no commit exposure.
+Conformance: A descriptor/mock check that one routed capability slice maps consistently
+across providers and frameworks. It verifies names, bindings, schemas, safe errors, and
+no commit exposure.

package/docs/governance/gate.md

@@ -1,15 +1,13 @@
 # Governance Gate
 
 `aicf gate` is a CI-friendly command that runs the public AICF checks in one
-deterministic pass. It coordinates validation, semantic invariants, governance
-risk, lifecycle posture, optional compatibility baselines, impact analysis,
-eval coverage, security-pack coverage, provider conformance, and public artifact
-hygiene.
+deterministic pass. It coordinates validation, semantic invariants, governance risk,
+lifecycle posture, optional compatibility baselines, impact analysis, eval coverage,
+security-pack coverage, provider conformance, and public artifact hygiene.
 
 The gate does not call models, run live provider SDKs, mutate manifests, execute
-handlers, write production stores, or expose commit tools to models.
-It does not call live integrations; provider conformance is descriptor/mock
-checking only.
+handlers, write production stores, or expose commit tools to models. It does not call
+live integrations; provider conformance is descriptor/mock checking only.
 
 ## Basic Usage
 
@@ -26,17 +24,17 @@ node dist/cli.js gate examples --env production --format json
 
 Exit codes are stable:
 
-| Code | Meaning |
-| --- | --- |
-| `0` | Gate passed. |
-| `1` | Validation or gate check failed. |
-| `2` | Usage or configuration error. |
-| `3` | Reserved for missing optional dependencies. |
-| `4` | Reserved for disabled live integrations or missing credentials. |
-| `5` | Unexpected internal error. |
+| Code | Meaning                                                         |
+| ---- | --------------------------------------------------------------- |
+| `0`  | Gate passed.                                                    |
+| `1`  | Validation or gate check failed.                                |
+| `2`  | Usage or configuration error.                                   |
+| `3`  | Reserved for missing optional dependencies.                     |
+| `4`  | Reserved for disabled live integrations or missing credentials. |
+| `5`  | Unexpected internal error.                                      |
 
-F8 does not run live integrations, so codes `3` and `4` are reserved for future
-optional paths or errors surfaced by existing optional helpers.
+F8 does not run live integrations, so codes `3` and `4` are reserved for future optional
+paths or errors surfaced by existing optional helpers.
 
 ## Configuration
 
@@ -70,9 +68,9 @@ gates:
     artifact_hygiene: true
 ```
 
-Enabled providers are descriptor/mock conformance targets. Provider aliases use
-the same normalization as provider conformance, for example `vercel-ai-sdk` maps
-to `ai-sdk` and `semantic-kernel` maps to `semantic-kernel-openapi`.
+Enabled providers are descriptor/mock conformance targets. Provider aliases use the same
+normalization as provider conformance, for example `vercel-ai-sdk` maps to `ai-sdk` and
+`semantic-kernel` maps to `semantic-kernel-openapi`.
 
 ## Production Defaults
 
@@ -80,14 +78,14 @@ When no config exists, the production gate uses conservative defaults:
 
 - warnings do not fail the gate unless `--fail-on-warnings` is supplied;
 - medium, high, and critical capabilities require eval coverage;
-- high and critical capabilities require assigned, generated, or waived
-  security-pack coverage;
+- high and critical capabilities require assigned, generated, or waived security-pack
+  coverage;
 - configured providers must pass conformance;
 - deprecated capabilities are blocked;
 - public artifact hygiene is enabled.
 
-Compatibility checks run only when `--baseline <path>` or
-`compatibility.baseline_root` is provided.
+Compatibility checks run only when `--baseline <path>` or `compatibility.baseline_root`
+is provided.
 
 ## CLI Options
 
@@ -101,10 +99,10 @@ aicf gate <manifest-root> --env <name> \
   [--no-artifact-hygiene]
 ```
 
-Use `--no-artifact-hygiene` only for narrow local debugging. Release checks
-should keep artifact hygiene enabled so private paths, traces, prompts, raw
-provider payloads, archives, Office/PDF artifacts, credential-looking files, and
-local-only material are rejected.
+Use `--no-artifact-hygiene` only for narrow local debugging. Release checks should keep
+artifact hygiene enabled so private paths, traces, prompts, raw provider payloads,
+archives, Office/PDF artifacts, credential-looking files, and local-only material are
+rejected.
 
 ## TypeScript
 
@@ -133,5 +131,5 @@ node dist/cli.js gate examples --env production --format json > gate-report.json
 node dist/cli.js evidence export examples --out evidence-pack.json --gate-report gate-report.json
 ```
 
-The evidence pack records gate, eval, security, and conformance gaps explicitly
-when reports are not supplied.
+The evidence pack records gate, eval, security, and conformance gaps explicitly when
+reports are not supplied.

package/docs/governance/impact-and-compatibility.md

@@ -1,9 +1,8 @@
 # Impact And Compatibility
 
 Compatibility checks compare two capability manifests and classify changes as
-compatible, minor, or breaking. Impact analysis reports direct registry
-coverage across entities, evals, prepare/commit links, policy references, and
-provider export relevance.
+compatible, minor, or breaking. Impact analysis reports direct registry coverage across
+entities, evals, prepare/commit links, policy references, and provider export relevance.
 
 Use: