@solvers-hub/llm-json 0.1.6 → 0.1.7

package/docs-md/README.md

@@ -4,7 +4,7 @@
 
 A TypeScript SDK for extracting and correcting JSON data from LLM outputs.
 
-[![npm version](https://badge.fury.io/js/llm-json.svg)](https://badge.fury.io/js/llm-json)
+[![npm version](https://badge.fury.io/js/llm-json.svg)](https://badge.fury.io/js/llm-json)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Overview
@@ -13,47 +13,96 @@ LLM-JSON is a lightweight library designed to parse and extract JSON objects fro
 
 ## Key Features
 
-- **Text/JSON Separation**: Cleanly separates text content from JSON data in LLM outputs
-- **Multiple JSON Support**: Extracts multiple JSON objects or arrays from a single input
-- **JSON Validation & Correction**: Automatically fixes common JSON formatting errors from LLMs
-- **Code Block Support**: Extracts JSON from markdown code blocks (```json)
+- **Text/JSON Separation**: Cleanly separates text content from JSON data in LLM outputs
+- **Multiple JSON Support**: Extracts multiple JSON objects or arrays from a single input
+- **JSON Validation & Correction**: Automatically fixes common JSON formatting errors from LLMs
+- **Code Block Support**: Extracts JSON from markdown code blocks (```json)
+- **Schema Validation**: Validates extracted JSON against provided schemas
 - **TypeScript Support**: Written in TypeScript with full type definitions
 
 ## Quick Start
 
 ### Installation
 
-```bash
-npm install llm-json
+```bash
+npm install @solvers-hub/llm-json
 ```
 
 ### Basic Usage
 
-```typescript
-import { LlmJson } from 'llm-json';
+```typescript
+import { LlmJson } from '@solvers-hub/llm-json';
 
 const llmOutput = `Here's some text followed by JSON:
 
-{
-  "name": "John",
-  "age": 30,
-  "skills": ["JavaScript", "TypeScript", "React"]
+{
+  "name": "John",
+  "age": 30,
+  "skills": ["JavaScript", "TypeScript", "React"]
 }`;
 
-const llmJson = new LlmJson({ attemptCorrection: true });
+const llmJson = new LlmJson({ attemptCorrection: true });
 const { text, json } = llmJson.extract(llmOutput);
 
-console.log(text); // ['Here\'s some text followed by JSON:']
-console.log(json); // [{ name: 'John', age: 30, skills: ['JavaScript', 'TypeScript', 'React'] }]
+console.log(text); // ['Here\'s some text followed by JSON:']
+console.log(json); // [{ name: 'John', age: 30, skills: ['JavaScript', 'TypeScript', 'React'] }]
 ```
 
-## Documentation
+### Schema Validation
+
+You can validate extracted JSON against schemas:
+
+```typescript
+import { LlmJson } from '@solvers-hub/llm-json';
+
+const schemas = [
+  {
+    name: 'person',
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'integer' }
+      },
+      required: ['name', 'age']
+    }
+  }
+];
+
+const llmJson = new LlmJson({ 
+  attemptCorrection: true,
+  schemas
+});
+
+const llmOutput = `Here's a person: {"name": "John", "age": 30}
+And some other data: {"title": "Meeting notes"}`;
+const result = llmJson.extract(llmOutput);
+
+// Note: All extracted JSON objects are included in the json array
+console.log(result.json);
+// [
+//   { name: 'John', age: 30 },
+//   { title: 'Meeting notes' }
+// ]
+
+// The validatedJson array includes validation results for each JSON object
+console.log(result.validatedJson);
+// [
+//   {
+//     json: { name: 'John', age: 30 },
+//     matchedSchema: 'person',
+//     isValid: true
+//   },
+//   {
+//     json: { title: 'Meeting notes' },
+//     matchedSchema: null,
+//     isValid: false,
+//     validationErrors: [...]  // Validation errors
+//   }
+// ]
 
-For detailed documentation including API references and examples:
-
-- [API Documentation](./docs/README.md)
-- [Examples](./docs/examples.md)
+```
 
 ## License
 
-MIT © 2023
+MIT © 2025

package/docs-md/classes/LlmJson.md

@@ -42,7 +42,7 @@ Creates a new LlmJson instance with the specified options.
 
 #### Defined in
 
-[index.ts:17](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/index.ts#L17)
+[index.ts:17](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/index.ts#L17)
 
 ## Properties
 
@@ -52,7 +52,7 @@ Creates a new LlmJson instance with the specified options.
 
 #### Defined in
 
-[index.ts:11](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/index.ts#L11)
+[index.ts:11](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/index.ts#L11)
 
 ___
 
@@ -62,7 +62,7 @@ ___
 
 #### Defined in
 
-[index.ts:10](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/index.ts#L10)
+[index.ts:10](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/index.ts#L10)
 
 ___
 
@@ -72,7 +72,7 @@ ___
 
 #### Defined in
 
-[index.ts:9](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/index.ts#L9)
+[index.ts:9](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/index.ts#L9)
 
 ## Methods
 
@@ -96,7 +96,7 @@ An object containing arrays of extracted text and JSON.
 
 #### Defined in
 
-[index.ts:39](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/index.ts#L39)
+[index.ts:39](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/index.ts#L39)
 
 ___
 
@@ -120,7 +120,7 @@ An object containing arrays of extracted text and JSON.
 
 #### Defined in
 
-[index.ts:48](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/index.ts#L48)
+[index.ts:48](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/index.ts#L48)
 
 ___
 
@@ -144,4 +144,4 @@ The LlmJson singleton instance.
 
 #### Defined in
 
-[index.ts:27](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/index.ts#L27)
+[index.ts:27](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/index.ts#L27)

package/docs-md/interfaces/ExtractOptions.md

@@ -9,6 +9,7 @@ Options for JSON extraction.
 ### Properties
 
 - [attemptCorrection](ExtractOptions.md#attemptcorrection)
+- [schemas](ExtractOptions.md#schemas)
 
 ## Properties
 
@@ -26,4 +27,23 @@ false
 
 #### Defined in
 
-[types.ts:9](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L9)
+[types.ts:9](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L9)
+
+___
+
+### schemas
+
+• `Optional` **schemas**: [`SchemaDefinition`](SchemaDefinition.md)[]
+
+JSON schemas to validate extracted JSON against.
+If provided, the extracted JSON will be validated against these schemas.
+
+**`Default`**
+
+```ts
+undefined
+```
+
+#### Defined in
+
+[types.ts:16](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L16)

package/docs-md/interfaces/ExtractResult.md

@@ -10,6 +10,7 @@ Result of the JSON extraction.
 
 - [json](ExtractResult.md#json)
 - [text](ExtractResult.md#text)
+- [validatedJson](ExtractResult.md#validatedjson)
 
 ## Properties
 
@@ -21,7 +22,7 @@ Array of parsed JSON objects extracted from the input.
 
 #### Defined in
 
-[types.ts:24](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L24)
+[types.ts:71](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L71)
 
 ___
 
@@ -33,4 +34,16 @@ Array of text blocks extracted from the input.
 
 #### Defined in
 
-[types.ts:19](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L19)
+[types.ts:66](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L66)
+
+___
+
+### validatedJson
+
+• `Optional` **validatedJson**: [`ValidationResult`](ValidationResult.md)[]
+
+Array of validated JSON results, only present if schemas were provided.
+
+#### Defined in
+
+[types.ts:76](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L76)

package/docs-md/interfaces/JsonBlock.md

@@ -24,7 +24,7 @@ The end index of the JSON block in the input string.
 
 #### Defined in
 
-[types.ts:44](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L44)
+[types.ts:96](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L96)
 
 ___
 
@@ -36,7 +36,7 @@ The parsed JSON object.
 
 #### Defined in
 
-[types.ts:54](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L54)
+[types.ts:106](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L106)
 
 ___
 
@@ -48,7 +48,7 @@ The raw JSON string.
 
 #### Defined in
 
-[types.ts:34](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L34)
+[types.ts:86](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L86)
 
 ___
 
@@ -60,7 +60,7 @@ The start index of the JSON block in the input string.
 
 #### Defined in
 
-[types.ts:39](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L39)
+[types.ts:91](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L91)
 
 ___
 
@@ -72,4 +72,4 @@ Whether the JSON was corrected.
 
 #### Defined in
 
-[types.ts:49](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L49)
+[types.ts:101](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L101)

package/docs-md/interfaces/JsonParseError.md

@@ -22,7 +22,7 @@ The original error message.
 
 #### Defined in
 
-[types.ts:64](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L64)
+[types.ts:116](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L116)
 
 ___
 
@@ -34,7 +34,7 @@ The position in the JSON string where the error occurred.
 
 #### Defined in
 
-[types.ts:74](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L74)
+[types.ts:126](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L126)
 
 ___
 
@@ -46,4 +46,4 @@ The raw JSON string that failed to parse.
 
 #### Defined in
 
-[types.ts:69](https://github.com/solvers-hub/llm-json/blob/4d60f7fa6cdcace0d353b33e3d79c6fd33db1860/src/types.ts#L69)
+[types.ts:121](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L121)

package/docs-md/interfaces/SchemaDefinition.md

@@ -0,0 +1,36 @@
+[@solvers-hub/llm-json](../README.md) / [Exports](../modules.md) / SchemaDefinition
+
+# Interface: SchemaDefinition
+
+Definition of a JSON schema for validation.
+
+## Table of contents
+
+### Properties
+
+- [name](SchemaDefinition.md#name)
+- [schema](SchemaDefinition.md#schema)
+
+## Properties
+
+### name
+
+• **name**: `string`
+
+A unique name for the schema to identify which schema matched.
+
+#### Defined in
+
+[types.ts:26](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L26)
+
+___
+
+### schema
+
+• **schema**: `object`
+
+The JSON schema object conforming to JSON Schema specification.
+
+#### Defined in
+
+[types.ts:31](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L31)

package/docs-md/interfaces/ValidationResult.md

@@ -0,0 +1,62 @@
+[@solvers-hub/llm-json](../README.md) / [Exports](../modules.md) / ValidationResult
+
+# Interface: ValidationResult
+
+Result of schema validation for a JSON object.
+
+## Table of contents
+
+### Properties
+
+- [isValid](ValidationResult.md#isvalid)
+- [json](ValidationResult.md#json)
+- [matchedSchema](ValidationResult.md#matchedschema)
+- [validationErrors](ValidationResult.md#validationerrors)
+
+## Properties
+
+### isValid
+
+• **isValid**: `boolean`
+
+Whether the JSON is valid according to the matched schema.
+
+#### Defined in
+
+[types.ts:51](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L51)
+
+___
+
+### json
+
+• **json**: `any`
+
+The JSON object that was validated.
+
+#### Defined in
+
+[types.ts:41](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L41)
+
+___
+
+### matchedSchema
+
+• **matchedSchema**: ``null`` \| `string`
+
+The name of the schema that matched, or null if no schema matched.
+
+#### Defined in
+
+[types.ts:46](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L46)
+
+___
+
+### validationErrors
+
+• `Optional` **validationErrors**: `any`[]
+
+Validation errors if any, or undefined if validation passed.
+
+#### Defined in
+
+[types.ts:56](https://github.com/solvers-hub/llm-json/blob/6d8d00890ee1d42b63f8bb8c3f6401333e41041e/src/types.ts#L56)

package/docs-md/modules.md

@@ -18,6 +18,8 @@
 - [ExtractResult](interfaces/ExtractResult.md)
 - [JsonBlock](interfaces/JsonBlock.md)
 - [JsonParseError](interfaces/JsonParseError.md)
+- [SchemaDefinition](interfaces/SchemaDefinition.md)
+- [ValidationResult](interfaces/ValidationResult.md)
 
 ## References
 

package/examples/array-example.ts

@@ -0,0 +1,69 @@
+import LlmJson from '../src/index';
+
+/**
+ * Example demonstrating how to use the LLM-JSON library for arrays.
+ */
+function runArrayExample() {
+    // Create an instance with auto-correction enabled
+    const llmJson = new LlmJson({ attemptCorrection: true });
+
+    // Simple array example
+    const simpleArrayInput = `Here is a list of names: ["John", "Jane", "Bob"]`;
+
+    console.log("=== Simple Array Example ===");
+
+    // Using extract - might not properly handle standalone arrays
+    const simpleExtractResult = llmJson.extract(simpleArrayInput);
+    console.log("With extract():");
+    console.log("Text:", simpleExtractResult.text);
+    console.log("JSON:", JSON.stringify(simpleExtractResult.json, null, 2));
+    console.log();
+
+    // Using extractAll - properly handles arrays
+    const simpleExtractAllResult = llmJson.extractAll(simpleArrayInput);
+    console.log("With extractAll():");
+    console.log("Text:", simpleExtractAllResult.text);
+    console.log("JSON:", JSON.stringify(simpleExtractAllResult.json, null, 2));
+    console.log();
+
+    // Complex array example
+    const complexArrayInput = `Here's an array of users:
+  [
+    {
+      "name": "John Doe",
+      "age": 30,
+      "skills": ["JavaScript", "TypeScript"]
+    },
+    {
+      "name": "Jane Smith",
+      "age": 28,
+      "skills": ["Python", "Machine Learning"]
+    }
+  ]`;
+
+    console.log("=== Complex Array Example ===");
+
+    // Using extractAll - properly handles complex arrays
+    const complexResult = llmJson.extractAll(complexArrayInput);
+    console.log("With extractAll():");
+    console.log("Text:", complexResult.text);
+    console.log("JSON:", JSON.stringify(complexResult.json, null, 2));
+    console.log();
+
+    // Multiple JSON structures example
+    const mixedInput = `Here's an object: {"name": "John", "age": 30}
+  
+  And here's an array: [1, 2, 3, 4, 5]
+  
+  And another object: {"city": "New York", "country": "USA"}`;
+
+    console.log("=== Mixed JSON Types Example ===");
+
+    // Using extractAll - handles both objects and arrays
+    const mixedResult = llmJson.extractAll(mixedInput);
+    console.log("With extractAll():");
+    console.log("Text:", mixedResult.text);
+    console.log("JSON:", JSON.stringify(mixedResult.json, null, 2));
+}
+
+runArrayExample(); 

package/examples/example.ts

@@ -0,0 +1,101 @@
+import LlmJson from '../src/index';
+
+/**
+ * Example demonstrating how to use the LLM-JSON library.
+ */
+function runExample() {
+  // Create an instance with auto-correction enabled
+  const llmJson = new LlmJson({ attemptCorrection: true });
+
+  // Example from the requirements
+  const input = `<research_planning>
+a. Summary: The given organization is unnamed and works in the area of "something new," which suggests an innovative or emerging field. This could involve novel technologies, fresh market approaches, or unexplored domains. Without specific details, assumptions about the sector or industry may involve startups, tech innovation, or trendsetting industries. The focus and goals may lean toward exploration, user adoption, and refinement of novel concepts.
+
+b. Potential Product Features: 
+   - Exploration of new technologies (VR/AR interfaces, IoT integration)
+   - User onboarding and education tools 
+   - Novel interaction models or user interfaces
+   - Feedback and improvement loops
+   - Community engagement and collaboration spaces
+
+c. User Persona: Considering the organization's innovative nature, the primary user could be an early adopter, tech-savvy individual who is curious and willing to explore new technologies. This persona is likely someone who enjoys experimenting with novel ideas and is motivated by the excitement of participating in pioneering efforts. 
+   Study Name: "Demo - Innovator Insight"
+
+d. Potential Research Objectives:
+   - Evaluate user onboarding process effectiveness in helping users understand the product's novel features.
+   - Assess user engagement with community collaboration spaces to identify areas for increased interaction.
+   - Verify the intuitiveness of new interaction models and user interfaces.
+   - Explore user satisfaction with feedback and improvement loops.
+   - Measure the impact of educational tools on user empowerment and confidence.
+   - Analyze user behavior patterns to refine product workflows.
+   - Investigate potential barriers to user adoption and retention.
+   
+e. Narrowing Down Objectives: 
+   After considering the potential research objectives, the focus shifted towards objectives that can be directly evaluated through a live web application. The final objectives chosen were geared towards user onboarding, interaction intuitiveness, and community engagement, as they align with the persona of an early adopter and focus on improving user experience in areas relevant to the organization's innovative nature.
+</research_planning>
+
+\`\`\`json
+{
+  "studyName": "Demo - Innovator Insight",
+  "userPersona": "Tech-savvy early adopter exploring new innovations.",
+  "objectives": [
+    {
+      "objectiveTitle": "Onboarding Process Evaluation",
+      "objectiveDescription": "Assess the effectiveness of the user onboarding process in enabling users to grasp the novel features of the product quickly and efficiently, ensuring that it enhances initial user engagement and reduces learning curves."
+    },
+    {
+      "objectiveTitle": "Community Interaction Analysis",
+      "objectiveDescription": "Investigate user engagement within community collaboration spaces, identifying potential improvements to foster more interaction, sharing, and collaboration among users, enhancing overall community dynamics."
+    },
+    {
+      "objectiveTitle": "Interface Intuition Verification",
+      "objectiveDescription": "Verify the intuitiveness of new interaction models and user interfaces, focusing on how users adapt and navigate through the product, aiming to identify any areas needing refinement for better usability."
+    }
+  ]
+}
+\`\`\``;
+
+  // Extract JSON and text
+  const result = llmJson.extract(input);
+
+  console.log("Extracted text:");
+  console.log("------------------");
+  result.text.forEach((text, index) => {
+    console.log(`Text block ${index + 1}:`);
+    console.log(text);
+    console.log();
+  });
+
+  console.log("Extracted JSON:");
+  console.log("------------------");
+  result.json.forEach((json, index) => {
+    console.log(`JSON object ${index + 1}:`);
+    console.log(JSON.stringify(json, null, 2));
+    console.log();
+  });
+
+  // Example with malformed JSON
+  console.log("\nExample with malformed JSON:");
+  console.log("---------------------------");
+
+  const malformedInput = `Here is some information:
+  
+  {
+    name: "John",
+    age: 30,
+    skills: ["JavaScript", "TypeScript"],
+    preferences: {
+      theme: "dark",
+      notifications: true,
+    }
+  }`;
+
+  const malformedResult = llmJson.extract(malformedInput);
+
+  console.log("Text:");
+  console.log(malformedResult.text[0]);
+  console.log("\nCorrected JSON:");
+  console.log(JSON.stringify(malformedResult.json[0], null, 2));
+}
+
+runExample();