@introspection-ai/recipes 0.13.0 → 0.14.0

package/docs/recipe-judges.md

@@ -1,152 +0,0 @@
-# Recipe judge definitions
-
-Recipe judges are optional, recipe-owned LLM grading definitions. Author them
-as direct children of `judges/` using a lowercase `.yaml` or `.yml` extension:
-
-```text
-my-recipe/
-  judges/
-    helpful.yaml
-```
-
-Nested files such as `judges/calibration/helpful.yaml` are not judge sources.
-The standalone `recipe-check` binary, `introspection check`, and in-memory
-bindings discover the same direct-child set and return the same validation
-result. Recipes without judge sources have no judge diagnostics or
-`resources.judges` count.
-
-## Ownership boundary
-
-`pi-recipe-check` owns the portable authored YAML specification and its static,
-file-oriented diagnostics. The I/O-free `check_recipe_files` core is the common
-validation path used by the filesystem checker, npm CLI, serialized snapshot
-API, and Python binding.
-
-The Introspection judge engine owns runtime evaluation: applicability
-execution, conversation assembly and transcript protection, model request
-construction, retries, verdict normalization, and evaluation identity. Runtime
-implementations should consume or remain explicitly compatible with the
-authored specification defined here; new authored fields must land in this
-checker and its contract tests rather than being introduced only in a runtime
-parser.
-
-The Rust checker and Python binding return a `Report` containing diagnostics
-and, when judges exist, a `resources.judges` source count. The report does not
-contain a normalized judge definition, `judge_id`, `definition_hash`, or
-registry projection. Migrating project-scoped registry projection away from
-the runtime parser is a separate platform change and must not add project or
-tenant context to this portable API.
-
-## Definition shape
-
-The minimal definition is:
-
-```yaml
-judge: helpful
-
-instructions: |
-  Determine whether the assistant answered the user correctly.
-
-llm:
-  model: gpt-5
-```
-
-`judge`, `instructions`, and `llm.model` are required and non-empty. Judge names
-must be unique across all judge files in one recipe. `llm.provider` defaults to
-`openai` at runtime.
-
-The canonical expanded definition is:
-
-```yaml
-judge: helpful
-description: Did the assistant answer correctly?
-
-on:
-  - event: message
-    match:
-      role: assistant
-
-instructions: |
-  Determine whether the assistant answered the user correctly.
-
-llm:
-  provider: openai
-  model: gpt-5
-  request:
-    temperature: 0
-    max_tokens: 1024
-    reasoning_effort: medium
-  transport:
-    timeout_ms: 60000
-    max_retries: 2
-    max_retry_delay_ms: 5000
-  local:
-    base_url: https://api.openai.com/v1
-    api_key_env: OPENAI_API_KEY
-```
-
-Unknown fields are errors at every level. The obsolete top-level `model:`
-block is rejected.
-
-### LLM settings
-
-- `provider` is a 1-64 byte lowercase slug containing ASCII letters, digits,
-  and hyphens. The portable checker does not restrict it to managed platform
-  providers because custom slugs can be used with an explicit local endpoint.
-- `model` is a trimmed, non-empty string of at most 255 bytes.
-- `request.temperature` is a finite number from 0 through 2 and defaults to 0.
-- `request.max_tokens` is an integer from 1 through 131072 when present;
-  explicit `null` is treated as omitted.
-- `request.reasoning_effort` is a 1-64 byte lowercase slug containing ASCII
-  letters and hyphens; explicit `null` is treated as omitted.
-- `transport.timeout_ms` is an integer from 1 through 600000 and defaults to
-  60000.
-- `transport.max_retries` is an integer from 0 through 10 and defaults to 0.
-- `transport.max_retry_delay_ms` is an integer from 0 through 60000 and
-  defaults to 5000.
-- `local` requires both `base_url` and `api_key_env`. The URL must be HTTP(S),
-  have a host, contain no embedded credentials, query, or fragment, and use
-  HTTPS unless it targets `localhost`, `127.0.0.1`, or `::1`. `api_key_env` is
-  an environment-variable name, not a credential value.
-
-Transport and local settings affect execution but not authored grading
-identity. The platform judge engine remains responsible for applying defaults,
-building requests, and enforcing runtime routing.
-
-## Applicability
-
-`on` is optional. Omission, an empty mapping, or an empty list makes the judge
-applicable to every conversation selected for judging. Otherwise it is an
-OR-list of matchers. Supported events are `message`, `tool`, and `feedback`;
-fields within one `match` mapping are ANDed by the runtime engine.
-
-```yaml
-on:
-  - event: message
-    match:
-      role: user
-      text: /refund|invoice/i
-  - event: tool
-    match:
-      name: shell
-      args.command: /pytest/i
-  - event: feedback
-    match:
-      sentiment: negative
-```
-
-Match keys are non-empty field paths. Regex literals use Rust regex syntax and
-support unique `i`, `m`, `s`, and `u` flags. `environment`, `runtime_group`, and
-paths ending in `pattern_id` are platform-owned and cannot appear as authored
-match fields. The runtime engine owns dotted-path traversal and actual gate
-evaluation.
-
-## Diagnostics
-
-Invalid recipe content is reported through the normal `Report`/`Diagnostic`
-model. Judge diagnostics use stable `judge.*` codes, recipe-relative source
-paths, useful help text, and deterministic ordering. YAML syntax failures use
-`judge.yaml_malformed` and include a 1-based source span when the parser
-provides one. Invalid definitions do not raise a separate content exception in
-the Python binding; they return `Report(valid=False, ...)` like other recipe
-errors.

package/docs/runtime-library.md

@@ -1,171 +0,0 @@
-# Runtime library
-
-The Recipes runtime library turns Recipe source into a live Pi agent. It is a
-library boundary, not a hosting framework.
-
-## The embedding ladder
-
-```text
-resolveRecipe()          read and resolve the portable package
-    │
-    ▼
-createRecipeSession()    construct the complete live Pi session
-    │
-    └── runRecipe()      execute one turn and dispose
-```
-
-Hosts should use the lowest layer that preserves their control.
-
-## `resolveRecipe`
-
-```ts
-import { resolveRecipe } from "@introspection-ai/recipes/recipe";
-
-const recipe = resolveRecipe({
-  recipeDir,
-  agentName,
-});
-```
-
-The result contains the selected agent, visible subagents, model settings,
-tools, MCP policy, skills, prompts, extensions, and system-prompt composition.
-It does not create a model client or start a session.
-
-## `createRecipeSession`
-
-```ts
-import { createRecipeSession } from "@introspection-ai/recipes/session";
-
-const handle = await createRecipeSession({
-  recipeDir,
-  agentName,
-  cwd: workspaceDir,
-  credentials,
-  modelOverride,
-  mcpBindings,
-  eventBus,
-  customTools,
-  extensionFactories,
-  runController,
-  agentToolOptions,
-  settingsManager,
-  sessionManager,
-  additionalSkillPaths,
-  skillPaths,
-  systemPrompt,
-  onDiagnostics,
-  onEvent,
-  otel: {
-    tracer,
-    meter,
-    meta: { conversationId },
-    runSpans: false,
-    getParentContext: () => currentTurnContext,
-  },
-});
-```
-
-This is the primary host integration point. It:
-
-- resolves the Recipe and selected agent;
-- resolves model credentials fail-closed;
-- materializes required MCP bindings fail-closed;
-- loads Recipe skills, prompts, and extensions;
-- registers the shared subagent tool;
-- creates and binds the Pi `AgentSession`;
-- returns one idempotent `dispose()` boundary.
-
-The returned `RecipeSessionHandle` exposes:
-
-- `session` — Pi prompt, steer, follow-up, abort, messages, and events;
-- `recipe` — the resolved portable definition;
-- `runs` — the subagent run controller;
-- `dispose()` — child, session, instrumentation, and MCP cleanup.
-
-Host injection is intentional. A managed host can supply durable session state,
-cross-process subagent execution, inline endpoint bindings, platform
-extensions, its own settings, an event bus, host tools, and a
-gateway-decorated model without reimplementing Recipe semantics. The Recipe
-continues to own model configuration and tool selection; host seams replace
-transport and materialized resources, not the portable definition.
-
-Default MCP materialization leases the supplied `env` object until the handle
-is disposed and restores its prior MCP/PATH state afterward. Concurrent
-materialized sessions must receive separate environment objects. A host that
-materializes one process-wide MCP runtime instead passes `mcpMode: "inherit"`
-to its sessions, as runtime-agent does.
-
-## `runRecipe`
-
-```ts
-import { runRecipe } from "@introspection-ai/recipes/run";
-
-const result = await runRecipe({
-  recipeDir,
-  cwd: workspaceDir,
-  prompt,
-  timeoutMs: 120_000,
-});
-```
-
-`runRecipe` creates one session, executes one prompt, returns the transcript and
-final text, and always disposes. It is suitable for tests, cron jobs, and queue
-workers that do not need a durable conversational host.
-
-## Inspection
-
-```ts
-import { inspectRecipe } from "@introspection-ai/recipes/inspect";
-
-const requirements = inspectRecipe(recipeDir);
-```
-
-Inspection derives agents, providers, expected credential variables, required
-and optional MCP servers, and resource counts without creating a session.
-
-## OpenTelemetry
-
-Pass a tracer through `otel` to attach the JS SDK's OpenTelemetry GenAI
-semantic-convention instrumentation to the session. Recipes derives default
-agent identity from the resolved package and generates a conversation id when
-the host does not provide one. The default in-process subagent controller
-inherits that conversation id while each child derives its own Recipe agent
-identity. Injected run controllers own their child-session instrumentation.
-
-Recipes does not create or register an OTel provider, processor, exporter, or
-global context manager. The host owns that pipeline and its content policy. A
-standalone host can therefore use the same standard OTLP exporter for
-Braintrust, Langfuse, an OTel Collector, or another compatible backend. A host
-that needs structure-only infrastructure traces can wrap that exporter with
-`GenAiContentScrubbingExporter` from
-`@introspection-sdk/introspection-pi`.
-
-Short-lived hosts must flush their own provider after `runRecipe` completes;
-long-lived hosts should flush and shut it down with the host lifecycle.
-
-## Host conformance
-
-```ts
-import { hostConformanceCases } from "@introspection-ai/recipes/test-utils";
-
-for (const testCase of hostConformanceCases(myHostAdapter)) {
-  it(testCase.name, testCase.run);
-}
-```
-
-Passing the suite means the host is using the same session construction
-contract as Pi and Introspection. Protocol behavior, persistence, tenancy, and
-deployment remain host-specific and require their own tests.
-
-## Deliberate non-features
-
-The package does not provide:
-
-- an HTTP server or wire protocol;
-- a task database or task state machine;
-- a scheduler or queue;
-- sandbox or tenant isolation;
-- a deployment CLI;
-- provider-specific hosting adapters.
-
-Those layers compose above `createRecipeSession`.