{"id":14986492,"url":"https://github.com/wrtnlabs/openai-function-schema","last_synced_at":"2025-04-11T20:31:49.869Z","repository":{"id":246902504,"uuid":"823081451","full_name":"wrtnlabs/openai-function-schema","owner":"wrtnlabs","description":"OpenAI Function Call Schema Composer and Executor from OpenAPI (Swagger) Document.","archived":true,"fork":false,"pushed_at":"2025-01-06T04:56:02.000Z","size":755,"stargazers_count":32,"open_issues_count":1,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T10:43:11.155Z","etag":null,"topics":["function-call-executor","function-call-schema","llm-function-call","openai-function-call","openapi","swagger"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wrtnlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-02T11:42:42.000Z","updated_at":"2025-03-24T10:34:38.000Z","dependencies_parsed_at":"2024-07-24T11:14:51.238Z","dependency_job_id":"997d8da2-8109-41b1-94f8-20a5fd293d34","html_url":"https://github.com/wrtnlabs/openai-function-schema","commit_stats":{"total_commits":39,"total_committers":3,"mean_commits":13.0,"dds":0.1282051282051282,"last_synced_commit":"9a8d0f781c72e590a51834f5573830db16e3495d"},"previous_names":["wrtnio/openai-function-schema","wrtnlabs/openai-function-schema"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrtnlabs%2Fopenai-function-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrtnlabs%2Fopenai-function-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrtnlabs%2Fopenai-function-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrtnlabs%2Fopenai-function-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wrtnlabs","download_url":"https://codeload.github.com/wrtnlabs/openai-function-schema/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248476337,"owners_count":21110260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["function-call-executor","function-call-schema","llm-function-call","openai-function-call","openapi","swagger"],"created_at":"2024-09-24T14:12:57.321Z","updated_at":"2025-04-11T20:31:44.856Z","avatar_url":"https://github.com/wrtnlabs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAI Function Schema\n![Wrtn Technologies](https://github.com/wrtnio/openai-function-schema/assets/13158709/48ee1578-f7cd-4e64-abd9-8354716ec0c9)\n\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/wrtnio/openai-function/blob/master/LICENSE)\n[![npm version](https://img.shields.io/npm/v/@wrtnio/openai-function-schema.svg)](https://www.npmjs.com/package/@wrtnio/openai-function-schema)\n[![Downloads](https://img.shields.io/npm/dm/@wrtnio/openai-function-schema.svg)](https://www.npmjs.com/package/@wrtnio/openai-function-schema)\n[![Build Status](https://github.com/wrtnio/openai-function-schema/workflows/build/badge.svg)](https://github.com/wrtnio/openai-function-schema/actions?query=workflow%3Abuild)\n\nOpenAI function call schema definition, converter and executor.\n\n`@wrtnio/openai-function-schema` supports OpenAI function call schema definitions, and converter from Swagger (OpenAPI) documents. About the converter from Swagger (OpenAPI) documents, `@wrtnio/openai-function-schema` supports every versions of them.\n\n  - Swagger v2.0\n  - OpenAPI v3.0\n  - OpenApi v3.1\n\nAlso, `@wrtnio/openai-function-schema` provides function call executor from [`IOpenAiDocument`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiDocument.ts) and [`IOpenAiFunction`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiDocument.ts), so that you can easily execute the remote Restful API operation with OpenAI composed arguments.\n\nLet's learn how to use it by example code of below.\n\n\n\n\n## Setup\n```bash\nnpm install @wrtnio/openai-function-schema\n```\n\n```typescript\nimport {\n  IOpenAiDocument,\n  IOpenAiFunction,\n  OpenAiComposer,\n  OpenAiFetcher,\n} from \"@wrtnio/openai-function-schema\";\nimport fs from \"fs\";\nimport typia from \"typia\";\nimport { v4 } from \"uuid\";\n\nimport { IBbsArticle } from \"../../../api/structures/IBbsArticle\";\n\nconst main = async (): Promise\u003cvoid\u003e =\u003e {\n  // COMPOSE OPENAI FUNCTION CALL SCHEMAS\n  const swagger = JSON.parse(\n    await fs.promises.readFile(\"swagger.json\", \"utf8\"),\n  );\n  const document: IOpenAiDocument = OpenAiComposer.document({ \n    swagger \n  });\n\n  // EXECUTE OPENAI FUNCTION CALL\n  const func: IOpenAiFunction = document.functions.find(\n    (f) =\u003e f.method === \"put\" \u0026\u0026 f.path === \"/bbs/articles\",\n  )!;\n  const article: IBbsArticle = await OpenAiFetcher.execute({\n    document,\n    function: func,\n    connection: { host: \"http://localhost:3000\" },\n    arguments: [\n      // imagine that arguments are composed by OpenAI\n      v4(),\n      typia.random\u003cIBbsArticle.ICreate\u003e(),\n    ],\n  });\n  typia.assert(article);\n};\nmain().catch(console.error);\n```\n\n\n\n\n## Features\nAbout supported features, please read description comments of each component.\n\nI'm preparing documentation and playground website of `@wrtnio/openai-function-schema` features. Until that, please read below components' description comments. Even though you have to read source code of each component, but description comments of them may satisfy you.\n\n- Schema Definitions\n  - [`IOpenAiDocument`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiDocument.ts): OpenAI function metadata collection with options\n  - [`IOpenAiFunction`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiFunction.ts): OpenAI's function metadata\n  - [`IOpenAiSchema`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiSchema.ts): Type schema info escaped `$ref`.\n- Functions\n  - [`OpenAiComposer`](https://github.com/wrtnio/openai-function-schema/blob/master/src/OpenAiComposer.ts): Compose `IOpenAiDocument` from Swagger (OpenAPI) document\n  - [`OpenAiFetcher`](https://github.com/wrtnio/openai-function-schema/blob/master/src/OpenAiFetcher.ts): Function call executor with `IOpenAiFunction`\n  - [`OpenAiDataCombiner`](https://github.com/wrtnio/openai-function-schema/blob/master/src/OpenAiDataCombiner.ts): Data combiner for LLM function call with human composed data\n  - [`OpenAiTypeChecker`](https://github.com/wrtnio/openai-function-schema/blob/master/src/OpenAiTypeChecker.ts): Type checker for `IOpenAiSchema`\n\n### Command Line Interface\n```bash\n########\n# LAUNCH CLI\n########\n# PRIOR TO NODE V20\nnpm install -g @wrtnio/openai-function-schema\nnpx wofs\n\n# SINCE NODE V20\nnpx @wrtnio/openai-function-schema\n\n########\n# PROMPT\n########\n--------------------------------------------------------\n Swagger to OpenAI Function Call Schema Converter\n--------------------------------------------------------\n? Swagger file path: test/swagger.json\n? OpenAI Function Call Schema file path: test/plain.json\n? Whether to wrap parameters into an object with keyword or not: No\n```\n\nConvert swagger to OpenAI function schema file by a CLI command.\n\nIf you run `npx @wrtnio/openai-function-schema` (or `npx wofs` after global setup), the CLI (Command Line Interface) will inquiry those arguments. After you fill all of them, the OpenAI function call schema file of [`IOpenAiDocument`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiDocument.ts) type would be created to the target location.\n\nIf you want to specify arguments without prompting, you can fill them like below:\n\n```bash\n# PRIOR TO NODE V20\nnpm install -g @wrtnio/openai-function-schema\nnpx wofs --input swagger.json --output openai.json --keyword false\n\n# SINCE NODE V20\nnpx @wrtnio/openai-function-schema\n  --input swagger.json \n  --output openai.json \n  --keyword false\n```\n\nHere is the list of [`IOpenAiDocument`](https://github.com/wrtnio/openai-function-schema/blob/main/src/structures/IOpenAiDocument.ts) files generated by CLI command.\n\nProject       | Swagger | Positional | Keyworded\n--------------|---------|--------|-----------\nBBS           | [swagger.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/swagger/bbs.json) | [positional.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/positional/bbs.json) | [keyworded.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/keyword/bbs.json)\nClickhouse    | [swagger.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/swagger/clickhouse.json) | [positional.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/positional/clickhouse.json) | [keyworded.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/keyword/clickhouse.json)\nFireblocks    | [swagger.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/swagger/fireblocks.json) | [positional.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/positional/fireblocks.json) | [keyworded.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/keyword/fireblocks.json)\nIamport       | [swagger.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/swagger/iamport.json) | [positional.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/positional/iamport.json) | [keyworded.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/keyword/iamport.json)\nPetStore      | [swagger.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/swagger/petstore.json) | [positional.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/positional/petstore.json) | [keyworded.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/keyword/petstore.json)\nShopping Mall | [swagger.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/swagger/shopping.json) | [positional.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/positional/shopping.json) | [keyworded.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/keyword/shopping.json)\nToss Payments | [swagger.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/swagger/toss.json) | [positional.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/positional/toss.json) | [keyworded.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/keyword/toss.json)\nUber          | [swagger.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/swagger/uber.json) | [positional.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/positional/uber.json) | [keyworded.json](https://github.com/wrtnio/openai-function-schema/blob/main/examples/keyword/uber.json)\n\n\n\n\n### Library API\nIf you want to utilize `@wrtnio/openai-function-schema` in the API level, you should start from composing [`IOpenAiDocument`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiDocument.ts) through `OpenAiComposer.document()` method. \n\nAfter composing the [`IOpenAiDocument`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiDocument.ts) data, you may provide the nested [`IOpenAiFunction`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiFunction.ts) instances to the OpenAI, and the OpenAI may compose the arguments by its function calling feature. With the OpenAI automatically composed arguments, you can execute the function call by `OpenAiFetcher.execute()` method.\n\nHere is the example code composing and executing the [`IOpenAiFunction`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiFunction.ts).\n\n  - Test Function: [test_fetcher_positional_bbs_article_update.ts](https://github.com/wrtnio/openai-function-schema/blob/main/test/features/fetcher/positional/test_fetcher_positional_bbs_article_update.ts)\n  - Backend Server Code: [BbsArticlesController.ts](https://github.com/wrtnio/openai-function-schema/blob/main/test/controllers/BbsArticlesController.ts)\n\n```typescript\nimport {\n  IOpenAiDocument,\n  IOpenAiFunction,\n  OpenAiComposer,\n  OpenAiFetcher,\n} from \"@wrtnio/openai-function-schema\";\nimport fs from \"fs\";\nimport typia from \"typia\";\nimport { v4 } from \"uuid\";\n\nimport { IBbsArticle } from \"../../../api/structures/IBbsArticle\";\n\nconst main = async (): Promise\u003cvoid\u003e =\u003e {\n  // COMPOSE OPENAI FUNCTION CALL SCHEMAS\n  const swagger = JSON.parse(\n    await fs.promises.readFile(\"swagger.json\", \"utf8\"),\n  );\n  const document: IOpenAiDocument = OpenAiComposer.document({ \n    swagger \n  });\n\n  // EXECUTE OPENAI FUNCTION CALL\n  const func: IOpenAiFunction = document.functions.find(\n    (f) =\u003e f.method === \"put\" \u0026\u0026 f.path === \"/bbs/articles\",\n  )!;\n  const article: IBbsArticle = await OpenAiFetcher.execute({\n    document,\n    function: func,\n    connection: { host: \"http://localhost:3000\" },\n    arguments: [\n      // imagine that arguments are composed by OpenAI\n      v4(),\n      typia.random\u003cIBbsArticle.ICreate\u003e(),\n    ],\n  });\n  typia.assert(article);\n};\nmain().catch(console.error);\n```\n\nBy the way, above example code's target operation function has multiple parameters. You know what? If you configure a function to have only one parameter by wrapping into one object type, OpenAI function calling feature constructs arguments a little bit efficiently than multiple parameters case.\n\nSuch only one object typed parameter is called `keyword parameter`, and `@wrtnio/openai-function-schema` supports such keyword parameterized function schemas. When composing [`IOpenAiDocument`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiDocument.ts) by `OpenAiComposer.document()` method, configures `option.keyword` to be `true`, then every [`IOpenAiFunction`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiFunction.ts) instances would be keyword parameterized. Also, `OpenAiFetcher` understands the keyword parameterized function specification, so that performs proper execution by automatic decomposing the arguments.\n\nHere is the example code of keyword parameterizing.\n\n  - Test Function: [test_fetcher_keyword_bbs_article_update.ts](https://github.com/wrtnio/openai-function-schema/blob/main/test/features/fetcher/keyword/test_fetcher_keyword_bbs_article_update.ts)\n  - Backend Server Code: [BbsArticlesController.ts](https://github.com/wrtnio/openai-function-schema/blob/main/test/controllers/BbsArticlesController.ts)\n\n```typescript\nimport {\n  IOpenAiDocument,\n  IOpenAiFunction,\n  OpenAiComposer,\n  OpenAiFetcher,\n} from \"@wrtnio/openai-function-schema\";\nimport fs from \"fs\";\nimport typia from \"typia\";\nimport { v4 } from \"uuid\";\n\nimport { IBbsArticle } from \"../../../api/structures/IBbsArticle\";\n\nconst main = async (): Promise\u003cvoid\u003e =\u003e {\n  // COMPOSE OPENAI FUNCTION CALL SCHEMAS\n  const swagger = JSON.parse(\n    await fs.promises.readFile(\"swagger.json\", \"utf8\"),\n  );\n  const document: IOpenAiDocument = OpenAiComposer.document({ \n    swagger,\n    options: {\n      keyword: true, // keyword parameterizing\n    }\n  });\n\n  // EXECUTE OPENAI FUNCTION CALL\n  const func: IOpenAiFunction = document.functions.find(\n    (f) =\u003e f.method === \"put\" \u0026\u0026 f.path === \"/bbs/articles\",\n  )!;\n  const article: IBbsArticle = await OpenAiFetcher.execute({\n    document,\n    function: func,\n    connection: { host: \"http://localhost:3000\" },\n    arguments: [\n      // imagine that argument is composed by OpenAI\n      {\n        id: v4(),\n        body: typia.random\u003cIBbsArticle.ICreate\u003e(),\n      },\n    ],\n  });\n  typia.assert(article);\n};\nmain().catch(console.error);\n```\n\nAt last, there can be some special API operation that some arguments must be composed by user, not by LLM (Large Language Model). For example, if an API operation requires file uploading or secret key identifier, it must be composed by user manually in the frontend application side.\n\nFor such case, `@wrtnio/openai-function-schema` supports special option [`IOpenAiDocument.IOptions.separate`](https://github.com/wrtnio/openai-function-schema/blob/master/src/structures/IOpenAiDocument.ts). If you configure the callback function, it would be utilized for determining whether the value must be composed by user or not. When the arguments are composed by both user and LLM sides, you can combine them into one through `OpenAiDataComposer.parameters()` method, so that you can still execute the function calling with `OpenAiFetcher.execute()` method.\n\nHere is the example code of such special case:\n\n  - Test Function: [test_combiner_keyword_parameters_query.ts](https://github.com/wrtnio/openai-function-schema/blob/main/test/features/combiner/test_combiner_keyword_parameters_query.ts)\n  - Backend Server Code: [MembershipController.ts](https://github.com/wrtnio/openai-function-schema/blob/main/test/controllers/MembershipController.ts)\n\n```typescript\nimport {\n  IOpenAiDocument,\n  IOpenAiFunction,\n  IOpenAiSchema,\n  OpenAiComposer,\n  OpenAiDataCombiner,\n  OpenAiFetcher,\n  OpenAiTypeChecker,\n} from \"@wrtnio/openai-function-schema\";\nimport fs from \"fs\";\nimport typia from \"typia\";\n\nimport { IMembership } from \"../../api/structures/IMembership\";\n\nconst main = async (): Promise\u003cvoid\u003e =\u003e {\n  // COMPOSE OPENAI FUNCTION CALL SCHEMAS\n  const swagger = JSON.parse(\n    await fs.promises.readFile(\"swagger.json\", \"utf8\"),\n  );\n  const document: IOpenAiDocument = OpenAiComposer.document({\n    swagger,\n    options: {\n      keyword: true,\n      separate: (schema: IOpenAiSchema) =\u003e\n        OpenAiTypeChecker.isString(schema) \u0026\u0026\n        (schema[\"x-wrtn-secret-key\"] !== undefined ||\n          schema[\"contentMediaType\"] !== undefined),\n    },\n  });\n\n  // EXECUTE OPENAI FUNCTION CALL\n  const func: IOpenAiFunction = document.functions.find(\n    (f) =\u003e f.method === \"patch\" \u0026\u0026 f.path === \"/membership/change\",\n  )!;\n  const membership: IMembership = await OpenAiFetcher.execute({\n    document,\n    function: func,\n    connection: { host: \"http://localhost:3000\" },\n    arguments: OpenAiDataCombiner.parameters({\n      function: func,\n      llm: [\n        // imagine that below argument is composed by OpenAI\n        {\n          body: {\n            name: \"Wrtn Technologies\",\n            email: \"master@wrtn.io\",\n            password: \"1234\",\n            age: 20,\n            gender: 1,\n          },\n        },\n      ],\n      human: [\n        // imagine that below argument is composed by human\n        {\n          query: {\n            secret: \"something\",\n          },\n          body: {\n            secretKey: \"something\",\n            picture: \"https://wrtn.io/logo.png\",\n          },\n        },\n      ],\n    }),\n  });\n  typia.assert(membership);\n};\nmain().catch(console.error);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwrtnlabs%2Fopenai-function-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwrtnlabs%2Fopenai-function-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwrtnlabs%2Fopenai-function-schema/lists"}