structured-json-agent 1.0.0

package/README.md

@@ -0,0 +1,125 @@
+# Structured JSON Agent
+
+A typed and extensible TypeScript library for creating and running Iterative AI Agents that guarantee structured JSON output.
+
+This library orchestrates a **Generator ↔ Reviewer** cycle to ensure that the output from Large Language Models (LLMs) strictly adheres to a defined JSON Schema.
+
+## Features
+
+*   **Guaranteed JSON Output**: Enforces strict adherence to JSON Schemas (Draft-07+).
+*   **Iterative Self-Correction**: Automatically detects validation errors and feeds them back to a "Reviewer" model to fix the output.
+*   **Type-Safe**: Built with TypeScript for full type inference and safety.
+*   **Model Agnostic**: Compatible with OpenAI by default, but extensible for other providers.
+*   **Production Ready**: Includes typed errors, extensive validation, and a clean API.
+
+## Installation
+
+```bash
+npm install structured-json-agent
+```
+
+## Usage
+
+### 1. Import and Configure
+
+```typescript
+import { StructuredAgent } from "structured-json-agent";
+
+// Define your Schemas
+const inputSchema = {
+  type: "object",
+  properties: {
+    topic: { type: "string" },
+    depth: { type: "string", enum: ["basic", "advanced"] }
+  },
+  required: ["topic", "depth"]
+};
+
+const outputSchema = {
+  type: "object",
+  properties: {
+    title: { type: "string" },
+    keyPoints: { type: "array", items: { type: "string" } },
+    summary: { type: "string" }
+  },
+  required: ["title", "keyPoints", "summary"]
+};
+
+// Initialize the Agent
+const agent = new StructuredAgent({
+  openAiApiKey: process.env.OPENAI_API_KEY!,
+  generatorModel: "gpt-4-turbo",
+  reviewerModel: "gpt-3.5-turbo", // Can be a faster/cheaper model for simple fixes
+  inputSchema,
+  outputSchema,
+  systemPrompt: "You are an expert summarizer. Create a structured summary based on the topic.",
+  maxIterations: 3 // Optional: Max correction attempts (default: 5)
+});
+```
+
+### 2. Run the Agent
+
+```typescript
+async function main() {
+  try {
+    const result = await agent.run({
+      topic: "Clean Architecture",
+      depth: "advanced"
+    });
+
+    console.log("Result:", result);
+    // Output is guaranteed to match outputSchema
+  } catch (error) {
+    console.error("Agent failed:", error);
+  }
+}
+
+main();
+```
+
+## How It Works
+
+1.  **Validation**: The input JSON is validated against the `inputSchema`.
+2.  **Generation**: The `generatorModel` creates an initial response based on the system prompt and input.
+3.  **Verification Loop**:
+    *   The response is parsed and validated against `outputSchema`.
+    *   **If Valid**: The result is returned immediately.
+    *   **If Invalid**: The `reviewerModel` is invoked with the invalid JSON, the specific validation errors, and the expected schema. It attempts to fix the JSON.
+4.  **Convergence**: This cycle repeats until a valid JSON is produced or `maxIterations` is reached.
+
+## API Reference
+
+### `StructuredAgent` Config
+
+| Property | Type | Description |
+|Col |Col |Col |
+| `openAiApiKey` | `string` | Your OpenAI API Key. |
+| `generatorModel` | `string` | Model ID for the initial generation (e.g., `gpt-4`). |
+| `reviewerModel` | `string` | Model ID for the review/correction phase. |
+| `inputSchema` | `object` | JSON Schema for validating the input. |
+| `outputSchema` | `object` | JSON Schema for the expected output. |
+| `systemPrompt` | `string` | Core instructions for the agent. |
+| `maxIterations` | `number?` | Max retries for correction. Default: 5. |
+| `modelConfig` | `ModelConfig?` | Optional parameters (temperature, etc.). |
+| `llmService` | `ILLMService?` | Optional custom LLM service implementation. |
+
+### Error Handling
+
+The library exports specific error classes for handling failures:
+
+*   `InvalidInputSchemaError`: Input schema is invalid.
+*   `InvalidOutputSchemaError`: Output schema is invalid.
+*   `SchemaValidationError`: Input data does not match the schema.
+*   `MaxIterationsExceededError`: The agent could not produce valid JSON within the limit.
+*   `LLMExecutionError`: Failure in communicating with the LLM provider.
+
+## Architecture
+
+The project is structured by domain:
+
+*   `src/agent`: Core orchestration logic.
+*   `src/schemas`: Validation logic using AJV.
+*   `src/llm`: Interface and implementation for LLM providers.
+*   `src/errors`: Custom error definitions.
+*   `src/types`: Shared interfaces.
+

package/dist/agent/index.d.ts

@@ -0,0 +1,15 @@
+import { AgentConfig } from "../types/index.js";
+export declare class StructuredAgent {
+    private schemaValidator;
+    private llmService;
+    private inputValidator;
+    private outputValidator;
+    private config;
+    constructor(config: AgentConfig);
+    run(inputJson: unknown): Promise<unknown>;
+    private generateInitialResponse;
+    private reviewResponse;
+    private validateOutput;
+    private parseJson;
+    private buildSystemPrompt;
+}

package/dist/agent/index.js

@@ -0,0 +1,150 @@
+import { SchemaValidator } from "../schemas/validator.js";
+import { OpenAILLMService } from "../llm/index.js";
+import { InvalidInputSchemaError, InvalidOutputSchemaError, SchemaValidationError, MaxIterationsExceededError, LLMExecutionError, } from "../errors/index.js";
+export class StructuredAgent {
+    schemaValidator;
+    llmService;
+    inputValidator;
+    outputValidator;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.schemaValidator = new SchemaValidator();
+        // Use provided LLM service or default to OpenAI
+        this.llmService = config.llmService || new OpenAILLMService(config.openAiApiKey);
+        try {
+            this.inputValidator = this.schemaValidator.compile(config.inputSchema);
+        }
+        catch (e) {
+            throw new InvalidInputSchemaError("Failed to compile input schema", e);
+        }
+        try {
+            this.outputValidator = this.schemaValidator.compile(config.outputSchema);
+        }
+        catch (e) {
+            throw new InvalidOutputSchemaError("Failed to compile output schema", e);
+        }
+    }
+    async run(inputJson) {
+        // 1. Validate Input
+        try {
+            this.schemaValidator.validate(this.inputValidator, inputJson);
+        }
+        catch (error) {
+            if (error instanceof SchemaValidationError) {
+                // Enhance error message if needed, but the original is good
+                throw error;
+            }
+            throw error;
+        }
+        const maxIterations = this.config.maxIterations ?? 5;
+        const history = [];
+        // 2. Initial Generation
+        let currentJson = await this.generateInitialResponse(inputJson);
+        history.push({ step: "generation", result: currentJson });
+        let validationResult = this.validateOutput(currentJson);
+        if (validationResult.valid) {
+            return currentJson;
+        }
+        // 3. Review Loop
+        for (let i = 0; i < maxIterations; i++) {
+            try {
+                currentJson = await this.reviewResponse(currentJson, validationResult.errors || [], inputJson // Context might be needed
+                );
+                history.push({ step: `review-${i + 1}`, result: currentJson });
+                validationResult = this.validateOutput(currentJson);
+                if (validationResult.valid) {
+                    return currentJson;
+                }
+            }
+            catch (error) {
+                // If LLM fails or parsing fails during review, we record it and continue?
+                // Or throw? The requirement says "return exclusively a valid JSON".
+                // If we can't continue, we should probably throw or let the loop hit max iterations.
+                // For now, let's treat execution errors as fatal or part of the attempt?
+                // If it's a parsing error, it's a validation error.
+                // If it's an API error, it's an LLMExecutionError.
+                if (error instanceof LLMExecutionError) {
+                    throw error;
+                }
+                // If JSON parse error in reviewResponse, it might be caught there.
+            }
+        }
+        throw new MaxIterationsExceededError(`Failed to generate valid JSON after ${maxIterations} review iterations`, history);
+    }
+    async generateInitialResponse(input) {
+        const messages = [
+            {
+                role: "system",
+                content: this.buildSystemPrompt(),
+            },
+            {
+                role: "user",
+                content: JSON.stringify(input),
+            },
+        ];
+        const responseText = await this.llmService.complete(messages, this.config.generatorModel, this.config.modelConfig);
+        return this.parseJson(responseText);
+    }
+    async reviewResponse(invalidJson, errors, originalInput) {
+        const messages = [
+            {
+                role: "system",
+                content: `You are a strict JSON reviewer. 
+Your task is to fix the provided JSON so it adheres to the Schema.
+Output ONLY the corrected JSON.`,
+            },
+            {
+                role: "user",
+                content: `Original Input Context: ${JSON.stringify(originalInput)}
+        
+The following JSON is INVALID based on the output schema:
+${JSON.stringify(invalidJson)}
+
+Validation Errors:
+${errors.join("\n")}
+
+Expected Output Schema:
+${JSON.stringify(this.config.outputSchema)}
+
+Please correct the JSON.`,
+            },
+        ];
+        const responseText = await this.llmService.complete(messages, this.config.reviewerModel, this.config.modelConfig);
+        return this.parseJson(responseText);
+    }
+    validateOutput(data) {
+        try {
+            this.schemaValidator.validate(this.outputValidator, data);
+            return { valid: true };
+        }
+        catch (error) {
+            if (error instanceof SchemaValidationError) {
+                const formattedErrors = this.schemaValidator.formatErrors(error.errors);
+                return { valid: false, errors: [formattedErrors] };
+            }
+            return { valid: false, errors: ["Unknown validation error"] };
+        }
+    }
+    parseJson(text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch (e) {
+            // If parsing fails, we return the text (as string) or null?
+            // But the flow expects unknown (object).
+            // If we return the text, the schema validation will likely fail (unless schema allows string).
+            // This allows the reviewer to see the malformed JSON text.
+            return text;
+        }
+    }
+    buildSystemPrompt() {
+        return `${this.config.systemPrompt}
+
+IMPORTANT: You must output strict JSON only.
+The output must adhere to the following JSON Schema:
+${JSON.stringify(this.config.outputSchema)}
+`;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"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"}

package/dist/errors/index.d.ts

@@ -0,0 +1,23 @@
+export declare class StructuredAgentError extends Error {
+    constructor(message: string);
+}
+export declare class InvalidInputSchemaError extends StructuredAgentError {
+    context?: unknown | undefined;
+    constructor(message: string, context?: unknown | undefined);
+}
+export declare class InvalidOutputSchemaError extends StructuredAgentError {
+    context?: unknown | undefined;
+    constructor(message: string, context?: unknown | undefined);
+}
+export declare class SchemaValidationError extends StructuredAgentError {
+    errors: unknown[];
+    constructor(message: string, errors: unknown[]);
+}
+export declare class MaxIterationsExceededError extends StructuredAgentError {
+    attempts: unknown[];
+    constructor(message: string, attempts: unknown[]);
+}
+export declare class LLMExecutionError extends StructuredAgentError {
+    originalError?: unknown | undefined;
+    constructor(message: string, originalError?: unknown | undefined);
+}

package/dist/errors/index.js

@@ -0,0 +1,43 @@
+export class StructuredAgentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+export class InvalidInputSchemaError extends StructuredAgentError {
+    context;
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+    }
+}
+export class InvalidOutputSchemaError extends StructuredAgentError {
+    context;
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+    }
+}
+export class SchemaValidationError extends StructuredAgentError {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.errors = errors;
+    }
+}
+export class MaxIterationsExceededError extends StructuredAgentError {
+    attempts;
+    constructor(message, attempts) {
+        super(message);
+        this.attempts = attempts;
+    }
+}
+export class LLMExecutionError extends StructuredAgentError {
+    originalError;
+    constructor(message, originalError) {
+        super(message);
+        this.originalError = originalError;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAClD,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,oBAAoB;IAC3B;IAApC,YAAY,OAAe,EAAS,OAAiB;QACnD,KAAK,CAAC,OAAO,CAAC,CAAC;QADmB,YAAO,GAAP,OAAO,CAAU;IAErD,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,oBAAoB;IAC5B;IAApC,YAAY,OAAe,EAAS,OAAiB;QACnD,KAAK,CAAC,OAAO,CAAC,CAAC;QADmB,YAAO,GAAP,OAAO,CAAU;IAErD,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,oBAAoB;IACzB;IAApC,YAAY,OAAe,EAAS,MAAiB;QACnD,KAAK,CAAC,OAAO,CAAC,CAAC;QADmB,WAAM,GAAN,MAAM,CAAW;IAErD,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,oBAAoB;IAC9B;IAApC,YAAY,OAAe,EAAS,QAAmB;QACrD,KAAK,CAAC,OAAO,CAAC,CAAC;QADmB,aAAQ,GAAR,QAAQ,CAAW;IAEvD,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,oBAAoB;IACrB;IAApC,YAAY,OAAe,EAAS,aAAuB;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QADmB,kBAAa,GAAb,aAAa,CAAU;IAE3D,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./agent/index.js";
+export * from "./errors/index.js";
+export * from "./types/index.js";
+export * from "./schemas/validator.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./agent/index.js";
+export * from "./errors/index.js";
+export * from "./types/index.js";
+// Export schemas validator if needed, but maybe not necessary for public API
+export * from "./schemas/validator.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,6EAA6E;AAC7E,cAAc,wBAAwB,CAAC"}

package/dist/llm/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./openai.js";

package/dist/llm/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./openai.js";
+//# sourceMappingURL=index.js.map

package/dist/llm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/dist/llm/openai.d.ts

@@ -0,0 +1,7 @@
+import { ILLMService, ChatMessage } from "./types.js";
+import { ModelConfig } from "../types/index.js";
+export declare class OpenAILLMService implements ILLMService {
+    private client;
+    constructor(apiKey: string);
+    complete(messages: ChatMessage[], model: string, config?: ModelConfig): Promise<string>;
+}

package/dist/llm/openai.js

@@ -0,0 +1,33 @@
+import OpenAI from "openai";
+import { LLMExecutionError } from "../errors/index.js";
+export class OpenAILLMService {
+    client;
+    constructor(apiKey) {
+        this.client = new OpenAI({
+            apiKey: apiKey,
+        });
+    }
+    async complete(messages, model, config) {
+        try {
+            const response = await this.client.chat.completions.create({
+                messages: messages,
+                model: model,
+                response_format: { type: "json_object" }, // Force JSON mode
+                temperature: config?.temperature ?? 0.7,
+                top_p: config?.top_p,
+                max_tokens: config?.max_tokens,
+                presence_penalty: config?.presence_penalty,
+                frequency_penalty: config?.frequency_penalty,
+            });
+            const content = response.choices[0]?.message?.content;
+            if (!content) {
+                throw new LLMExecutionError("Received empty response from LLM");
+            }
+            return content;
+        }
+        catch (error) {
+            throw new LLMExecutionError("Failed to execute LLM request", error);
+        }
+    }
+}
+//# sourceMappingURL=openai.js.map

package/dist/llm/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/llm/openai.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAG5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAS;IAEvB,YAAY,MAAc;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC;YACvB,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;IACL,CAAC;IAEM,KAAK,CAAC,QAAQ,CACnB,QAAuB,EACvB,KAAa,EACb,MAAoB;QAEpB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;gBACzD,QAAQ,EAAE,QAAQ;gBAClB,KAAK,EAAE,KAAK;gBACZ,eAAe,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,kBAAkB;gBAC5D,WAAW,EAAE,MAAM,EAAE,WAAW,IAAI,GAAG;gBACvC,KAAK,EAAE,MAAM,EAAE,KAAK;gBACpB,UAAU,EAAE,MAAM,EAAE,UAAU;gBAC9B,gBAAgB,EAAE,MAAM,EAAE,gBAAgB;gBAC1C,iBAAiB,EAAE,MAAM,EAAE,iBAAiB;aAC7C,CAAC,CAAC;YAEH,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC;YACtD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,IAAI,iBAAiB,CAAC,kCAAkC,CAAC,CAAC;YAClE,CAAC;YAED,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,iBAAiB,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;CACF"}

package/dist/llm/types.d.ts

@@ -0,0 +1,8 @@
+import { ModelConfig } from "../types/index.js";
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface ILLMService {
+    complete(messages: ChatMessage[], model: string, config?: ModelConfig): Promise<string>;
+}

package/dist/llm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/llm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":""}

package/dist/schemas/validator.d.ts

@@ -0,0 +1,20 @@
+import type { ValidateFunction } from "ajv";
+export declare class SchemaValidator {
+    private ajv;
+    constructor();
+    /**
+     * Compiles a schema and returns a validation function.
+     * Throws InvalidInputSchemaError if the schema is invalid.
+     */
+    compile(schema: object): ValidateFunction;
+    /**
+     * Validates data against a compiled schema validator.
+     * Returns true if valid.
+     * Throws SchemaValidationError if invalid.
+     */
+    validate(validator: ValidateFunction, data: unknown): void;
+    /**
+     * Helper to format AJV errors into a readable string
+     */
+    formatErrors(errors: any[]): string;
+}

package/dist/schemas/validator.js

@@ -0,0 +1,39 @@
+import Ajv from "ajv";
+import { SchemaValidationError, InvalidInputSchemaError } from "../errors/index.js";
+export class SchemaValidator {
+    ajv;
+    constructor() {
+        // @ts-ignore: Ajv import structure compatibility
+        this.ajv = new Ajv({ allErrors: true, strict: false });
+    }
+    /**
+     * Compiles a schema and returns a validation function.
+     * Throws InvalidInputSchemaError if the schema is invalid.
+     */
+    compile(schema) {
+        try {
+            return this.ajv.compile(schema);
+        }
+        catch (error) {
+            throw new InvalidInputSchemaError("Invalid JSON Schema provided", error);
+        }
+    }
+    /**
+     * Validates data against a compiled schema validator.
+     * Returns true if valid.
+     * Throws SchemaValidationError if invalid.
+     */
+    validate(validator, data) {
+        const valid = validator(data);
+        if (!valid) {
+            throw new SchemaValidationError("Data validation failed", validator.errors || []);
+        }
+    }
+    /**
+     * Helper to format AJV errors into a readable string
+     */
+    formatErrors(errors) {
+        return this.ajv.errorsText(errors);
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/schemas/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/schemas/validator.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,KAAK,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAEpF,MAAM,OAAO,eAAe;IAClB,GAAG,CAAM;IAEjB;QACE,iDAAiD;QACjD,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IACzD,CAAC;IAED;;;OAGG;IACI,OAAO,CAAC,MAAc;QAC3B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,uBAAuB,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,QAAQ,CAAC,SAA2B,EAAE,IAAa;QACxD,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,qBAAqB,CAC7B,wBAAwB,EACxB,SAAS,CAAC,MAAM,IAAI,EAAE,CACvB,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACI,YAAY,CAAC,MAAa;QAC/B,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/types/index.d.ts

@@ -0,0 +1,26 @@
+import { ILLMService } from "../llm/types.js";
+export interface ModelConfig {
+    temperature?: number;
+    top_p?: number;
+    max_tokens?: number;
+    presence_penalty?: number;
+    frequency_penalty?: number;
+}
+export interface AgentConfig {
+    openAiApiKey: string;
+    generatorModel: string;
+    reviewerModel: string;
+    inputSchema: object;
+    outputSchema: object;
+    systemPrompt: string;
+    modelConfig?: ModelConfig;
+    maxIterations?: number;
+    llmService?: ILLMService;
+}
+export interface AgentRunOptions {
+    input: unknown;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "structured-json-agent",
+  "version": "1.0.0",
+  "description": "A typed and extensible library for creating and running Iterative AI Agents that generate structured JSON output.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "prepublishOnly": "npm run build",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "json",
+    "schema",
+    "openai",
+    "structured-output",
+    "llm"
+  ],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "openai": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}