@struktur/sdk 1.2.1 → 2.1.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.1.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": "2.1.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/auth/config.ts

@@ -3,11 +3,24 @@ import os from "node:os";
 import { chmod, mkdir } from "node:fs/promises";
 import type { ParserDef, ParsersConfig } from "@struktur/sdk";
 
+type TelemetryConfig = {
+  enabled: boolean;
+  provider: string;
+  url?: string;
+  apiKey?: string;
+  projectName?: string;
+  publicKey?: string; // For Langfuse
+  secretKey?: string; // For Langfuse
+  baseUrl?: string; // For Langfuse
+  sampleRate?: number;
+};
+
 type ConfigStore = {
   version: 1;
   defaultModel?: string;
   aliases?: Record<string, string>;
   parsers?: ParsersConfig;
+  telemetry?: TelemetryConfig;
 };
 
 const CONFIG_DIR_ENV = "STRUKTUR_CONFIG_DIR";
@@ -127,3 +140,47 @@ export const deleteParser = async (mimeType: string): Promise<boolean> => {
   await writeConfigStore(store);
   return true;
 };
+
+// --- Telemetry config management ---
+
+export const getTelemetryConfig = async (): Promise<TelemetryConfig | undefined> => {
+  const store = await readConfigStore();
+  return store.telemetry;
+};
+
+export const setTelemetryConfig = async (config: TelemetryConfig): Promise<void> => {
+  const store = await readConfigStore();
+  store.telemetry = config;
+  await writeConfigStore(store);
+};
+
+export const enableTelemetry = async (
+  provider: string,
+  options: Omit<TelemetryConfig, "enabled" | "provider">
+): Promise<void> => {
+  const store = await readConfigStore();
+  store.telemetry = {
+    enabled: true,
+    provider,
+    ...options,
+  };
+  await writeConfigStore(store);
+};
+
+export const disableTelemetry = async (): Promise<void> => {
+  const store = await readConfigStore();
+  if (store.telemetry) {
+    store.telemetry.enabled = false;
+  }
+  await writeConfigStore(store);
+};
+
+export const deleteTelemetryConfig = async (): Promise<boolean> => {
+  const store = await readConfigStore();
+  if (!store.telemetry) {
+    return false;
+  }
+  delete store.telemetry;
+  await writeConfigStore(store);
+  return true;
+};

package/src/extract.ts

@@ -34,29 +34,52 @@ export const extract = async <T>(
   options: ExtractionOptions<T>,
 ): Promise<ExtractionResult<T>> => {
   const debug = options.debug;
+  const telemetry = options.telemetry;
 
-  // Validate mutual exclusion and resolve the concrete schema early so that
-  // every strategy receives a fully-populated options object.
-  let resolvedOptions: ExtractionOptions<T>;
-  try {
-    const schema = resolveSchema(options);
-    resolvedOptions = { ...options, schema };
-  } catch (error) {
-    debug?.extractionComplete({
-      success: false,
-      totalInputTokens: 0,
-      totalOutputTokens: 0,
-      totalTokens: 0,
-      error: (error as Error).message,
-    });
-    return {
-      data: null as unknown as T,
-      usage: emptyUsage,
-      error: error as Error,
-    };
+  // Initialize telemetry if provided
+  if (telemetry) {
+    await telemetry.initialize();
   }
 
+  // Start root extraction span
+  const rootSpan = telemetry?.startSpan({
+    name: "struktur.extract",
+    kind: "CHAIN",
+    attributes: {
+      "extraction.strategy": options.strategy?.name ?? "default",
+      "extraction.artifacts.count": options.artifacts.length,
+    },
+  });
+
   try {
+    // Validate mutual exclusion and resolve the concrete schema early so that
+    // every strategy receives a fully-populated options object.
+    let resolvedOptions: ExtractionOptions<T>;
+    try {
+      const schema = resolveSchema(options);
+      resolvedOptions = { ...options, schema };
+    } catch (error) {
+      debug?.extractionComplete({
+        success: false,
+        totalInputTokens: 0,
+        totalOutputTokens: 0,
+        totalTokens: 0,
+        error: (error as Error).message,
+      });
+
+      telemetry?.endSpan(rootSpan!, {
+        status: "error",
+        error: error as Error,
+      });
+      await telemetry?.shutdown();
+
+      return {
+        data: null as unknown as T,
+        usage: emptyUsage,
+        error: error as Error,
+      };
+    }
+
     const total = resolvedOptions.strategy.getEstimatedSteps?.(resolvedOptions.artifacts);
 
     debug?.strategyRunStart({
@@ -95,6 +118,13 @@ export const extract = async <T>(
       error: result.error?.message,
     });
 
+    telemetry?.endSpan(rootSpan!, {
+      status: result.error ? "error" : "ok",
+      output: result.data,
+      error: result.error,
+    });
+    await telemetry?.shutdown();
+
     return result;
   } catch (error) {
     debug?.extractionComplete({
@@ -105,6 +135,12 @@ export const extract = async <T>(
       error: (error as Error).message,
     });
 
+    telemetry?.endSpan(rootSpan!, {
+      status: "error",
+      error: error as Error,
+    });
+    await telemetry?.shutdown();
+
     return {
       data: null as unknown as T,
       usage: emptyUsage,

package/src/index.ts

@@ -10,6 +10,14 @@ export type {
   Usage,
   AnyJSONSchema,
   TypedJSONSchema,
+  // Agent event types
+  AgentEvents,
+  AgentToolStartInfo,
+  AgentToolEndInfo,
+  AgentMessageInfo,
+  AgentReasoningInfo,
+  // Telemetry
+  TelemetryAdapter,
 } from "./types";
 
 export { extract } from "./extract";
@@ -45,6 +53,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 +73,7 @@ export {
   listProviderModels,
   resolveCheapestModel,
 } from "./llm/models";
+export { resolveModel } from "./llm/resolveModel";
 
 // Validation
 export { SchemaValidationError } from "./validation/validator";
@@ -79,6 +91,11 @@ export {
   getParser,
   setParser,
   deleteParser,
+  getTelemetryConfig,
+  setTelemetryConfig,
+  enableTelemetry,
+  disableTelemetry,
+  deleteTelemetryConfig,
 } from "./auth/config";
 export {
   listStoredProviders,