@struktur/sdk 1.2.1 → 2.0.0

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 mateffy
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -36,8 +36,7 @@ bun add @struktur/sdk
 ## Quick Example
 
 ```ts
-import { extract, simple, urlToArtifact } from "@struktur/sdk";
-import { openai } from "@ai-sdk/openai";
+import { extract, agent, urlToArtifact } from "@struktur/sdk";
 import type { JSONSchemaType } from "ajv";
 
 type Invoice = { number: string; vendor: string; total: number };
@@ -58,13 +57,18 @@ const artifact = await urlToArtifact("https://example.com/invoice.pdf");
 const result = await extract({
   artifacts: [artifact],
   schema,
-  strategy: simple({ model: openai("gpt-4o-mini") }),
+  strategy: agent({
+    provider: "anthropic",
+    modelId: "claude-sonnet-4",
+  }),
 });
 
 console.log(result.data.number); // fully typed
 console.log(result.usage.totalTokens);
 ```
 
+The **Agent strategy** is the default. It autonomously explores documents using a virtual filesystem and extracts data incrementally. For specific use cases, other strategies like `simple`, `parallel`, and `sequential` are also available.
+
 ## Documentation
 
 Full documentation at **[struktur.sh](https://struktur.sh)**

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@struktur/sdk",
-  "version": "1.2.1",
+  "version": "2.0.0",
+  "license": "FSL-1.1-MIT",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -19,6 +20,7 @@
     "@ai-sdk/google": "^3.0.0",
     "@ai-sdk/openai": "^3.0.0",
     "@openrouter/ai-sdk-provider": "^2.0.0",
+    "@struktur/agent-strategy": "1.0.0",
     "ai": "^6.0.97",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",

package/src/agent-cli-integration.test.ts

@@ -0,0 +1,47 @@
+import { test, expect, describe } from "bun:test";
+import { agent, AgentStrategy } from "@struktur/sdk";
+
+describe("Agent Strategy CLI Integration", () => {
+  test("agent strategy accepts provider and modelId", () => {
+    const strategy = agent<{ name: string }>({
+      provider: "anthropic",
+      modelId: "claude-sonnet-4",
+      maxSteps: 30,
+    });
+
+    expect(strategy).toBeInstanceOf(AgentStrategy);
+    expect(strategy.name).toBe("agent");
+    expect(strategy.getEstimatedSteps()).toBe(30);
+  });
+
+  test("agent strategy works with openai", () => {
+    const strategy = agent<{ name: string }>({
+      provider: "openai",
+      modelId: "gpt-4o",
+      maxSteps: 50,
+    });
+
+    expect(strategy).toBeInstanceOf(AgentStrategy);
+    expect(strategy.name).toBe("agent");
+  });
+
+  test("agent strategy works with openrouter nested paths", () => {
+    const strategy = agent<{ name: string }>({
+      provider: "openrouter",
+      modelId: "anthropic/claude-sonnet-4",
+      maxSteps: 50,
+    });
+
+    expect(strategy).toBeInstanceOf(AgentStrategy);
+    expect(strategy.name).toBe("agent");
+  });
+
+  test("agent strategy uses default maxSteps", () => {
+    const strategy = agent<{ name: string }>({
+      provider: "anthropic",
+      modelId: "claude-sonnet-4",
+    });
+
+    expect(strategy.getEstimatedSteps()).toBe(50);
+  });
+});

package/src/agent-export.test.ts

@@ -0,0 +1,17 @@
+import { test, expect } from "bun:test";
+import { agent, AgentStrategy } from "@struktur/sdk";
+
+test("agent strategy is exported from @struktur/sdk", () => {
+  expect(agent).toBeDefined();
+  expect(typeof agent).toBe("function");
+});
+
+test("AgentStrategy class is exported from @struktur/sdk", () => {
+  const strategy = agent({
+    provider: "anthropic",
+    modelId: "claude-sonnet-4",
+    maxSteps: 10,
+  });
+  expect(strategy).toBeInstanceOf(AgentStrategy);
+  expect(strategy.name).toBe("agent");
+});

package/src/agent-tool-labels.test.ts

@@ -0,0 +1,50 @@
+import { test, expect, describe } from "bun:test";
+import { agent, AgentStrategy } from "@struktur/sdk";
+
+describe("Agent Strategy Tool Labels", () => {
+  test("strategy creates properly configured agent", () => {
+    const strategy = agent<{ title: string }>({
+      provider: "anthropic",
+      modelId: "claude-sonnet-4",
+      maxSteps: 25,
+    });
+
+    expect(strategy).toBeDefined();
+    expect(strategy.name).toBe("agent");
+  });
+
+  test("label format for read tool with file path only", () => {
+    const label = "Read artifact.json";
+    expect(label).toBe("Read artifact.json");
+  });
+
+  test("label format for read tool with limit", () => {
+    const label = "Read artifact.json (limit 100)";
+    expect(label).toBe("Read artifact.json (limit 100)");
+  });
+
+  test("label format for read tool with offset and limit", () => {
+    const label = "Read artifact.json (offset 101, limit 100)";
+    expect(label).toBe("Read artifact.json (offset 101, limit 100)");
+  });
+
+  test("label format for bash command", () => {
+    const label = "Bash: cat /artifacts/artifact.json";
+    expect(label).toBe("Bash: cat /artifacts/artifact.json");
+  });
+
+  test("label format for grep", () => {
+    const label = 'Grep "pattern" in artifact.json';
+    expect(label).toBe('Grep "pattern" in artifact.json');
+  });
+
+  test("label format for find", () => {
+    const label = 'Find "*.json" in /artifacts';
+    expect(label).toBe('Find "*.json" in /artifacts');
+  });
+
+  test("label format for ls", () => {
+    const label = "List /artifacts (recursive)";
+    expect(label).toBe("List /artifacts (recursive)");
+  });
+});

package/src/artifacts/AGENTS.md

@@ -1,6 +1,6 @@
 Artifacts module
 
-- Purpose: convert external inputs into Artifact DTOs and manage parser configuration.
+- Purpose: convert external inputs into Artifacts and manage parser configuration.
 - Key files: `fileToArtifact.ts`, `urlToArtifact.ts`, `providers.ts`, `input.ts`.
 - Design: `ParsersConfig` is the unified configuration system for all parsers (npm packages, CLI commands, and inline handlers). The `providers` registry is deprecated — use inline parsers in `ParsersConfig` instead.
 - `parse` accepts an optional `parserConfig: ParsersConfig` (from `src/parsers/types`) that takes priority over the deprecated providers registry. Custom parsers are resolved by MIME type.

package/src/index.ts

@@ -45,6 +45,9 @@ export {
 
 export * from "./strategies";
 
+// Agent strategy (re-exported from @struktur/agent-strategy)
+export { AgentStrategy, agent, type AgentStrategyConfig } from "@struktur/agent-strategy";
+
 // Parsers public API
 export { collectStream } from "./parsers/collect";
 export type { ParserDef, ParsersConfig, InlineParserDef, NpmParserDef } from "./parsers/types";
@@ -62,6 +65,7 @@ export {
   listProviderModels,
   resolveCheapestModel,
 } from "./llm/models";
+export { resolveModel } from "./llm/resolveModel";
 
 // Validation
 export { SchemaValidationError } from "./validation/validator";

package/src/llm/LLMClient.test.ts

@@ -194,3 +194,201 @@ test("generateStructured uses custom schema description", async () => {
 
   expect(calls[0]?.output).toHaveProperty("description", "Extract data");
 });
+
+test("generateStructured shows friendly error when model doesn't support images", async () => {
+  calls.length = 0;
+  generateTextImpl = async () => {
+    throw {
+      responseBody: '{"error":{"message":"No endpoints found that support image input","code":404}}',
+      statusCode: 404,
+    };
+  };
+
+  expect(
+    async () =>
+      await generateStructured({
+        model: { modelId: "meta-llama/llama-3.1-8b-instruct" },
+        schema: { type: "object" },
+        system: "sys",
+        user: [{ type: "text", text: "prompt" }, { type: "image", image: "base64data" }],
+      }),
+  ).toThrow(
+    'Model "meta-llama/llama-3.1-8b-instruct" does not support image input. Please use a model that supports images (e.g., gpt-4o, claude-3-5-sonnet, gemini-1.5-pro) or remove the --images and --screenshots flags.',
+  );
+});
+
+test("generateStructured rethrows other API errors", async () => {
+  calls.length = 0;
+  const originalError = new Error("Some other error");
+  generateTextImpl = async () => {
+    throw originalError;
+  };
+
+  expect(
+    async () =>
+      await generateStructured({
+        model: {},
+        schema: { type: "object" },
+        system: "sys",
+        user: "prompt",
+      }),
+  ).toThrow("Some other error");
+});
+
+test("generateStructured shows friendly error for internal server error", async () => {
+  calls.length = 0;
+  generateTextImpl = async () => {
+    throw {
+      statusCode: 200,
+      responseBody: undefined,
+      data: {
+        code: 500,
+        message: "Internal Server Error",
+        type: null,
+        param: null,
+      },
+    };
+  };
+
+  expect(
+    async () =>
+      await generateStructured({
+        model: { modelId: "openai/gpt-5-mini" },
+        schema: { type: "object" },
+        system: "sys",
+        user: "prompt",
+      }),
+  ).toThrow(
+    'Provider error for model "openai/gpt-5-mini": Internal server error. The model or provider may be experiencing issues. Please try again or use a different model.',
+  );
+});
+
+test("generateStructured shows friendly error for authentication failure", async () => {
+  calls.length = 0;
+  generateTextImpl = async () => {
+    throw {
+      statusCode: 401,
+      responseBody: '{"error":{"message":"Invalid API key"}}',
+      data: {
+        code: 401,
+        message: "Invalid API key",
+      },
+    };
+  };
+
+  expect(
+    async () =>
+      await generateStructured({
+        model: { modelId: "gpt-4o" },
+        schema: { type: "object" },
+        system: "sys",
+        user: "prompt",
+      }),
+  ).toThrow(
+    'Authentication failed for model "gpt-4o". Please check your API key is valid and has the necessary permissions.',
+  );
+});
+
+test("generateStructured shows friendly error for rate limit", async () => {
+  calls.length = 0;
+  generateTextImpl = async () => {
+    throw {
+      statusCode: 429,
+      responseBody: '{"error":{"message":"Rate limit exceeded"}}',
+      data: {
+        code: 429,
+        message: "Rate limit exceeded",
+      },
+    };
+  };
+
+  expect(
+    async () =>
+      await generateStructured({
+        model: { modelId: "claude-3-5-sonnet" },
+        schema: { type: "object" },
+        system: "sys",
+        user: "prompt",
+      }),
+  ).toThrow(
+    'Rate limit exceeded for model "claude-3-5-sonnet". Please wait a moment and try again, or use a different model.',
+  );
+});
+
+test("generateStructured shows friendly error for model not found", async () => {
+  calls.length = 0;
+  generateTextImpl = async () => {
+    throw {
+      statusCode: 404,
+      responseBody: '{"error":{"message":"Model not found"}}',
+      data: {
+        code: 404,
+        message: "Model not found",
+      },
+    };
+  };
+
+  expect(
+    async () =>
+      await generateStructured({
+        model: { modelId: "nonexistent-model" },
+        schema: { type: "object" },
+        system: "sys",
+        user: "prompt",
+      }),
+  ).toThrow(
+    'Model "nonexistent-model" not found or unavailable. Model not found Please check the model name or try a different model.',
+  );
+});
+
+test("generateStructured shows friendly error for access denied", async () => {
+  calls.length = 0;
+  generateTextImpl = async () => {
+    throw {
+      statusCode: 403,
+      responseBody: '{"error":{"message":"Access denied"}}',
+      data: {
+        code: 403,
+        message: "Access denied",
+      },
+    };
+  };
+
+  expect(
+    async () =>
+      await generateStructured({
+        model: { modelId: "gpt-4-turbo" },
+        schema: { type: "object" },
+        system: "sys",
+        user: "prompt",
+      }),
+  ).toThrow(
+    'Access denied for model "gpt-4-turbo". Your API key may not have access to this model. Please check your subscription or try a different model.',
+  );
+});
+
+test("generateStructured shows generic provider error message", async () => {
+  calls.length = 0;
+  generateTextImpl = async () => {
+    throw {
+      statusCode: 400,
+      responseBody: '{"error":{"message":"Context length exceeded"}}',
+      data: {
+        code: 400,
+        message: "Context length exceeded",
+      },
+    };
+  };
+
+  expect(
+    async () =>
+      await generateStructured({
+        model: { modelId: "gpt-3.5-turbo" },
+        schema: { type: "object" },
+        system: "sys",
+        user: "prompt",
+      }),
+  ).toThrow(
+    'Provider error for model "gpt-3.5-turbo": Context length exceeded',
+  );
+});

package/src/llm/LLMClient.ts

@@ -61,26 +61,103 @@ export const generateStructured = async <T>(
       }
     : undefined;
 
-  const result = await generateText({
-    model: request.model as ModelType,
-    output: Output.object({
-      schema: schema as GenerateTextParams extends { schema: infer S }
-        ? S
-        : never,
-      name: request.schemaName ?? "extract",
-      description: request.schemaDescription,
-    }),
-    providerOptions: {
-      openai: {
-        strictJsonSchema: request.strict ?? false,
+  let result;
+  try {
+    result = await generateText({
+      model: request.model as ModelType,
+      output: Output.object({
+        schema: schema as GenerateTextParams extends { schema: infer S }
+          ? S
+          : never,
+        name: request.schemaName ?? "extract",
+        description: request.schemaDescription,
+      }),
+      providerOptions: {
+        openai: {
+          strictJsonSchema: request.strict ?? false,
+        },
       },
-    },
-    system: request.system,
-    messages: (request.messages ?? [
-      { role: "user", content: request.user },
-    ]) as MessageType,
-    ...(providerOptions ? { providerOptions } : {}),
-  });
+      system: request.system,
+      messages: (request.messages ?? [
+        { role: "user", content: request.user },
+      ]) as MessageType,
+      ...(providerOptions ? { providerOptions } : {}),
+    });
+  } catch (error) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "responseBody" in error &&
+      "statusCode" in error
+    ) {
+      const apiError = error as {
+        responseBody: unknown;
+        statusCode: number;
+        data?: {
+          code?: number;
+          message?: string;
+          type?: string | null;
+          param?: string | null;
+        };
+      };
+
+      const modelId =
+        typeof request.model === "object" && request.model !== null
+          ? (request.model as { modelId?: string }).modelId ??
+            JSON.stringify(request.model)
+          : String(request.model);
+
+      const responseBody = apiError.responseBody;
+      const errorData = apiError.data;
+
+      if (
+        typeof responseBody === "string" &&
+        responseBody.includes("No endpoints found that support image input")
+      ) {
+        throw new Error(
+          `Model "${modelId}" does not support image input. Please use a model that supports images (e.g., gpt-4o, claude-3-5-sonnet, gemini-1.5-pro) or remove the --images and --screenshots flags.`,
+        );
+      }
+
+      if (errorData?.code === 500 || errorData?.message?.includes("Internal Server Error")) {
+        throw new Error(
+          `Provider error for model "${modelId}": Internal server error. The model or provider may be experiencing issues. Please try again or use a different model.`,
+        );
+      }
+
+      if (apiError.statusCode === 401 || errorData?.code === 401) {
+        throw new Error(
+          `Authentication failed for model "${modelId}". Please check your API key is valid and has the necessary permissions.`,
+        );
+      }
+
+      if (apiError.statusCode === 403 || errorData?.code === 403) {
+        throw new Error(
+          `Access denied for model "${modelId}". Your API key may not have access to this model. Please check your subscription or try a different model.`,
+        );
+      }
+
+      if (apiError.statusCode === 429 || errorData?.code === 429) {
+        throw new Error(
+          `Rate limit exceeded for model "${modelId}". Please wait a moment and try again, or use a different model.`,
+        );
+      }
+
+      if (apiError.statusCode === 404 || errorData?.code === 404) {
+        const errorMsg = errorData?.message || "Model not found";
+        throw new Error(
+          `Model "${modelId}" not found or unavailable. ${errorMsg} Please check the model name or try a different model.`,
+        );
+      }
+
+      if (errorData?.message) {
+        throw new Error(
+          `Provider error for model "${modelId}": ${errorData.message}`,
+        );
+      }
+    }
+    throw error;
+  }
 
   const usageRaw = result.usage ?? {};
   const inputTokens =

package/src/llm/resolveModel.ts

@@ -0,0 +1,86 @@
+import { resolveProviderEnvVar, resolveProviderToken } from "../auth/tokens";
+
+export const resolveModel = async (model: string) => {
+  (globalThis as { AI_SDK_LOG_WARNINGS?: boolean }).AI_SDK_LOG_WARNINGS ??= false;
+  process.env.AI_SDK_LOG_WARNINGS ??= "false";
+  const [provider, ...rest] = model.split("/");
+  const modelName = rest.join("/");
+
+  if (!provider || !modelName) {
+    throw new Error(`Invalid model format: ${model}. Expected format: provider/model (e.g., openai/gpt-4)`);
+  }
+
+  const envVar = resolveProviderEnvVar(provider);
+  if (envVar && !process.env[envVar]) {
+    const storedToken = await resolveProviderToken(provider);
+    if (storedToken) {
+      process.env[envVar] = storedToken;
+    }
+  }
+
+  switch (provider) {
+    case "openai": {
+      const { openai } = await import("@ai-sdk/openai");
+      return openai(modelName);
+    }
+    case "anthropic": {
+      const { anthropic } = await import("@ai-sdk/anthropic");
+      return anthropic(modelName);
+    }
+    case "google": {
+      const { google } = await import("@ai-sdk/google");
+      return google(modelName);
+    }
+    case "opencode": {
+      const envVar = resolveProviderEnvVar("opencode");
+      let apiKey = envVar ? process.env[envVar] : undefined;
+      if (!apiKey) {
+        apiKey = await resolveProviderToken("opencode");
+      }
+      if (!apiKey) {
+        throw new Error("OpenCode API key is required. Set OPENCODE_API_KEY environment variable or run 'struktur auth set --provider opencode --token <token>'");
+      }
+      
+      if (modelName.startsWith("claude-")) {
+        const { createAnthropic } = await import("@ai-sdk/anthropic");
+        return createAnthropic({
+          apiKey,
+          baseURL: "https://opencode.ai/zen/v1",
+        })(modelName);
+      } else if (modelName.startsWith("gemini-")) {
+        const { createGoogleGenerativeAI } = await import("@ai-sdk/google");
+        return createGoogleGenerativeAI({
+          apiKey,
+          baseURL: "https://opencode.ai/zen/v1",
+        })(modelName);
+      } else {
+        const { createOpenAI } = await import("@ai-sdk/openai");
+        return createOpenAI({
+          apiKey,
+          baseURL: "https://opencode.ai/zen/v1",
+        })(modelName);
+      }
+    }
+    case "openrouter": {
+      const { openrouter } = await import("@openrouter/ai-sdk-provider");
+      const hashIndex = modelName.indexOf("#");
+      const actualModelName = hashIndex >= 0 ? modelName.slice(0, hashIndex) : modelName;
+      const preferredProvider = hashIndex >= 0 ? modelName.slice(hashIndex + 1) : undefined;
+      
+      const modelInstance = openrouter(actualModelName);
+      
+      if (preferredProvider) {
+        Object.defineProperty(modelInstance, "__openrouter_provider", {
+          value: preferredProvider,
+          writable: false,
+          enumerable: false,
+          configurable: false,
+        });
+      }
+      
+      return modelInstance;
+    }
+    default:
+      throw new Error(`Unsupported model provider: ${provider}. Supported providers: openai, anthropic, google, opencode, openrouter`);
+  }
+};

package/src/types.ts

@@ -49,6 +49,7 @@ export type StepInfo = {
   step: number;
   total?: number;
   label?: string;
+  detail?: string;
 };
 
 export type ProgressInfo = {

package/src/validation/AGENTS.md

@@ -1,6 +1,7 @@
 Validation module
 
-- Purpose: Ajv schema validation and error shaping.
+- Purpose: Schema validation and error shaping.
 - Key files: `validator.ts`.
-- Design: `validateOrThrow` compiles schemas and throws `SchemaValidationError` on failure; `createAjv` registers `ajv-formats` for common schema formats.
+- Design: `validateOrThrow` compiles schemas and throws `SchemaValidationError` on failure; `createAjv` registers `ajv-formats` for common schema formats and adds custom `artifact-id` format for referencing images in artifacts.
+- Custom formats: `artifact-id` validates strings matching pattern `artifact:ID/images/imageNUM.EXT` (e.g., `artifact:123456/images/image1.jpg`).
 - Tests: `validator.test.ts`.

package/src/validation/validator.test.ts

@@ -82,6 +82,38 @@ test("createAjv supports common formats", () => {
   }
 });
 
+test("createAjv supports artifact-id format", () => {
+  const ajv = createAjv();
+  const schema: JSONSchemaType<string> = { type: "string", format: "artifact-id" };
+
+  const validData = validateOrThrow<string>(ajv, schema, "artifact:123456/images/image1.jpg");
+  expect(validData).toBe("artifact:123456/images/image1.jpg");
+
+  const validData2 = validateOrThrow<string>(ajv, schema, "artifact:abc-xyz/images/image10.png");
+  expect(validData2).toBe("artifact:abc-xyz/images/image10.png");
+
+  try {
+    validateOrThrow<string>(ajv, schema, "not-an-artifact-id");
+    throw new Error("Expected validation error");
+  } catch (error) {
+    expect(error).toBeInstanceOf(SchemaValidationError);
+  }
+
+  try {
+    validateOrThrow<string>(ajv, schema, "artifact:123/images/image");
+    throw new Error("Expected validation error");
+  } catch (error) {
+    expect(error).toBeInstanceOf(SchemaValidationError);
+  }
+
+  try {
+    validateOrThrow<string>(ajv, schema, "https://example.com/image.jpg");
+    throw new Error("Expected validation error");
+  } catch (error) {
+    expect(error).toBeInstanceOf(SchemaValidationError);
+  }
+});
+
 test("isRequiredError identifies required constraint violations", () => {
   const requiredError = { 
     keyword: "required", 

package/src/validation/validator.ts

@@ -19,6 +19,8 @@ export class SchemaValidationError extends Error {
   }
 }
 
+const ARTIFACT_ID_PATTERN = /^artifact:[^/]+\/images\/image\d+\.\w+$/;
+
 export const createAjv = () => {
   const ajv = new Ajv({
     allErrors: true,
@@ -26,6 +28,12 @@ export const createAjv = () => {
     allowUnionTypes: true,
   });
   addFormats(ajv);
+  
+  ajv.addFormat("artifact-id", {
+    type: "string",
+    validate: (data: string) => ARTIFACT_ID_PATTERN.test(data),
+  });
+  
   return ajv;
 };