@typia/utils 12.0.0-dev.20260225

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Jeongho Nam
+
+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

@@ -0,0 +1,79 @@
+# `@typia/utils`
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/typia/blob/master/LICENSE)
+[![NPM Version](https://img.shields.io/npm/v/typia.svg)](https://www.npmjs.com/package/typia)
+[![NPM Downloads](https://img.shields.io/npm/dm/typia.svg)](https://www.npmjs.com/package/typia)
+
+Utility functions and converters for the [`typia`](https://github.com/samchon/typia) ecosystem.
+
+Automatically installed as a dependency of `typia`.
+
+## Key Exports
+
+| Module | Description |
+|--------|-------------|
+| `HttpLlm` | Create LLM controllers from OpenAPI documents and execute function calls |
+| `HttpMigration` | HTTP migration utilities |
+| `HttpError` | HTTP error type |
+| `LlmSchemaConverter` | Convert JSON Schema to LLM schema |
+| `OpenApiConverter` | Convert between OpenAPI versions |
+| `LlmTypeChecker` | Type checker for LLM schemas |
+| `OpenApiTypeChecker` | Type checker for OpenAPI documents |
+| `stringifyValidationFailure` | Format validation errors for LLM-friendly feedback |
+
+## `stringifyValidationFailure`
+
+Formats validation errors as annotated JSON for LLM-friendly feedback:
+
+```typescript
+import { IValidation } from "@typia/interface";
+import { stringifyValidationFailure } from "@typia/utils";
+
+const validation: IValidation<unknown> = func.validate(llmArguments);
+if (validation.success === false) {
+  console.log(stringifyValidationFailure(validation));
+}
+```
+
+Output:
+
+```json
+{
+  "x": "not a number", // ❌ expected: number
+  "y": 5
+}
+```
+
+## `HttpLlm`
+
+Create LLM controllers from OpenAPI documents:
+
+```typescript
+import { IHttpLlmController } from "@typia/interface";
+import { HttpLlm } from "@typia/utils";
+
+// any OpenAPI version (Swagger 2.0, OpenAPI 3.0/3.1) is accepted
+const controller: IHttpLlmController = HttpLlm.controller({
+  name: "shopping",
+  document: await fetch("https://shopping.example.com/swagger.json").then(r => r.json()),
+  connection: {
+    host: "https://shopping.example.com",
+    headers: { Authorization: "Bearer ..." },
+  },
+});
+
+// use with @typia/langchain, @typia/mcp, or @typia/vercel
+toLangChainTools({ controllers: [controller] });
+registerMcpControllers({ server, controllers: [controller] });
+toVercelTools({ controllers: [controller] });
+```
+
+`OpenApiConverter` is used internally to normalize any OpenAPI version into a unified format. You can also use it directly:
+
+```typescript
+import { OpenApi, OpenApiV3 } from "@typia/interface";
+import { OpenApiConverter } from "@typia/utils";
+
+const emended: OpenApi.IDocument = OpenApiConverter.upgradeDocument(swagger2doc); // Swagger 2.0 → OpenApi
+const downgraded: OpenApiV3.IDocument = OpenApiConverter.downgradeDocument(emended, "3.0"); // → OpenAPI 3.0
+```

package/lib/converters/LlmSchemaConverter.d.ts

@@ -0,0 +1,102 @@
+import { IJsonSchemaTransformError, ILlmFunction, ILlmSchema, IResult, OpenApi } from "@typia/interface";
+/**
+ * OpenAPI to LLM schema converter.
+ *
+ * `LlmSchemaConverter` converts OpenAPI JSON schemas to LLM-compatible
+ * {@link ILlmSchema} format. LLMs don't fully support JSON Schema, so this
+ * simplifies schemas by removing unsupported features (tuples, `const`, mixed
+ * unions).
+ *
+ * Main functions:
+ *
+ * - {@link parameters}: Convert object schema to {@link ILlmSchema.IParameters}
+ * - {@link schema}: Convert any schema to {@link ILlmSchema}
+ * - {@link separate}: Split parameters into LLM-fillable vs human-required
+ * - {@link invert}: Extract constraints from description back to schema
+ *
+ * Configuration options ({@link ILlmSchema.IConfig}):
+ *
+ * - `reference`: Allow `$ref` references (reduces tokens but may confuse LLM)
+ * - `strict`: OpenAI structured output mode (all properties required)
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare namespace LlmSchemaConverter {
+    /**
+     * Get configuration with defaults applied.
+     *
+     * @param config Partial configuration
+     * @returns Full configuration with defaults
+     */
+    const getConfig: (config?: Partial<ILlmSchema.IConfig> | undefined) => ILlmSchema.IConfig;
+    /**
+     * Convert OpenAPI object schema to LLM parameters schema.
+     *
+     * @param props.config Conversion configuration
+     * @param props.components OpenAPI components for reference resolution
+     * @param props.schema Object or reference schema to convert
+     * @param props.accessor Error path accessor
+     * @param props.refAccessor Reference path accessor
+     * @returns Converted parameters or error
+     */
+    const parameters: (props: {
+        config?: Partial<ILlmSchema.IConfig>;
+        components: OpenApi.IComponents;
+        schema: OpenApi.IJsonSchema.IObject | OpenApi.IJsonSchema.IReference;
+        accessor?: string;
+        refAccessor?: string;
+    }) => IResult<ILlmSchema.IParameters, IJsonSchemaTransformError>;
+    /**
+     * Convert OpenAPI schema to LLM schema.
+     *
+     * @param props.config Conversion configuration
+     * @param props.components OpenAPI components for reference resolution
+     * @param props.$defs Definition store (mutated with referenced types)
+     * @param props.schema Schema to convert
+     * @param props.accessor Error path accessor
+     * @param props.refAccessor Reference path accessor
+     * @returns Converted schema or error
+     */
+    const schema: (props: {
+        config?: Partial<ILlmSchema.IConfig>;
+        components: OpenApi.IComponents;
+        $defs: Record<string, ILlmSchema>;
+        schema: OpenApi.IJsonSchema;
+        accessor?: string;
+        refAccessor?: string;
+    }) => IResult<ILlmSchema, IJsonSchemaTransformError>;
+    /**
+     * Convert LLM schema back to OpenAPI schema.
+     *
+     * Restores constraint information from description tags and converts `$defs`
+     * references to `#/components/schemas`.
+     *
+     * @param props.components Target components (mutated with definitions)
+     * @param props.schema LLM schema to invert
+     * @param props.$defs LLM schema definitions
+     * @returns OpenAPI JSON schema
+     */
+    const invert: (props: {
+        components: OpenApi.IComponents;
+        schema: ILlmSchema;
+        $defs: Record<string, ILlmSchema>;
+    }) => OpenApi.IJsonSchema;
+    /**
+     * Separate parameters into LLM and human parts.
+     *
+     * Splits parameters based on predicate (human-side if true). Creates separate
+     * schemas for LLM-fillable and human-required fields.
+     *
+     * @param props.parameters Parameters schema to separate
+     * @param props.predicate Returns true for human-side properties
+     * @param props.convention Key naming convention for separated types
+     * @param props.equals Whether to use strict equality validation
+     * @returns Separated LLM and human parameter schemas
+     */
+    const separate: (props: {
+        parameters: ILlmSchema.IParameters;
+        predicate: (schema: ILlmSchema) => boolean;
+        convention?: (key: string, type: "llm" | "human") => string;
+        equals?: boolean;
+    }) => ILlmFunction.ISeparated;
+}