# Function schema
[](https://github.com/comfuture/function-schema/actions/workflows/ci.yml)
[](https://github.com/comfuture/function-schema/actions/workflows/python-publish.yml)
[](https://badge.fury.io/py/function-schema)
This is a small utility to generate JSON schemas for python functions.
With power of type annotations, it is possible to generate a schema for a function without describing it twice.
At this moment, extracting schema from a function is useful for [OpenAI Assistant Toll Calling](https://platform.openai.com/docs/assistants/tools/function-calling), [OpenAI API function-call](https://platform.openai.com/docs/guides/function-calling), and [Anthropic Claude Toll calling](https://docs.anthropic.com/claude/docs/tool-use) feature.
And it can be used for other purposes for example to generate documentation in the future.
## Installation
```sh
pip install function-schema
```
## Usage
```python
from typing import Annotated, Optional
import enum
def get_weather(
city: Annotated[str, "The city to get the weather for"],
unit: Annotated[
Optional[str],
"The unit to return the temperature in",
enum.Enum("Unit", "celcius fahrenheit")
] = "celcius",
) -> str:
"""Returns the weather for the given city."""
return f"Weather for {city} is 20°C"
```
Function description is taken from the docstring.
Type hinting with `typing.Annotated` for annotate additional information about the parameters and return type.
- type can be `typing.Union`, `typing.Optional`. (`T | None` for python 3.10+)
- string value of `Annotated` is used as a description
- enum value of `Annotated` is used as an enum schema
```python
import json
from function_schema import get_function_schema
schema = get_function_schema(get_weather)
print(json.dumps(schema, indent=2))
```
Will output:
```json
{
"name": "get_weather",
"description": "Returns the weather for the given city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city to get the weather for"
},
"unit": {
"type": "string",
"description": "The unit to return the temperature in",
"enum": [
"celcius",
"fahrenheit"
],
"default": "celcius"
}
},
}
"required": [
"city"
]
}
```
for claude, you should pass 2nd argument as SchemaFormat.claude or `claude`:
```python
from function_schema import get_function_schema
schema = get_function_schema(get_weather, "claude")
```
Please refer to the [Claude tool use](https://docs.anthropic.com/claude/docs/tool-use) documentation for more information.
You can use this schema to make a function call in OpenAI API:
```python
import openai
openai.api_key = "sk-..."
# Create an assistant with the function
assistant = client.beta.assistants.create(
instructions="You are a weather bot. Use the provided functions to answer questions.",
model="gpt-4-turbo-preview",
tools=[{
"type": "function",
"function": get_function_schema(get_weather),
}]
)
run = client.beta.messages.create(
assistant_id=assistant.id,
messages=[
{"role": "user", "content": "What's the weather like in Seoul?"}
]
)
# or with chat completion
result = openai.chat.completion.create(
model="gpt-3.5-turbo",
messages=[
{"role": "user", "content": "What's the weather like in Seoul?"}
],
tools=[get_function_schema(get_weather)],
tool_call="auto",
)
```
In claude api,
```python
import anthropic
client = anthropic.Client()
response = client.beta.tools.messages.create(
model="claude-3-opus-20240229",
max_tokens=4096,
tools=[get_function_schema(get_weather, "claude")],
messages=[
{"role": "user", "content": "What's the weather like in Seoul?"}
]
)
```
### CLI usage
```sh
function_schema mymodule.py my_function
```
## License
MIT License
Raw data
{
"_id": null,
"home_page": null,
"name": "function-schema",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Changkyun Kim <comfuture@gmail.com>",
"keywords": "json-schema, function, documentation, openai, utility",
"author": null,
"author_email": "Changkyun Kim <comfuture@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/42/17/00ea1ad99c97b96c3b25a2c3accc7288ced382113ba503fab9074a4ba653/function_schema-0.3.4.tar.gz",
"platform": null,
"description": "# Function schema\n\n[](https://github.com/comfuture/function-schema/actions/workflows/ci.yml)\n[](https://github.com/comfuture/function-schema/actions/workflows/python-publish.yml)\n[](https://badge.fury.io/py/function-schema)\n\nThis is a small utility to generate JSON schemas for python functions.\nWith power of type annotations, it is possible to generate a schema for a function without describing it twice.\n\nAt this moment, extracting schema from a function is useful for [OpenAI Assistant Toll Calling](https://platform.openai.com/docs/assistants/tools/function-calling), [OpenAI API function-call](https://platform.openai.com/docs/guides/function-calling), and [Anthropic Claude Toll calling](https://docs.anthropic.com/claude/docs/tool-use) feature.\nAnd it can be used for other purposes for example to generate documentation in the future.\n\n## Installation\n\n```sh\npip install function-schema\n```\n\n## Usage\n\n```python\nfrom typing import Annotated, Optional\nimport enum\n\ndef get_weather(\n city: Annotated[str, \"The city to get the weather for\"],\n unit: Annotated[\n Optional[str],\n \"The unit to return the temperature in\",\n enum.Enum(\"Unit\", \"celcius fahrenheit\")\n ] = \"celcius\",\n) -> str:\n \"\"\"Returns the weather for the given city.\"\"\"\n return f\"Weather for {city} is 20\u00b0C\"\n```\n\nFunction description is taken from the docstring.\nType hinting with `typing.Annotated` for annotate additional information about the parameters and return type.\n\n- type can be `typing.Union`, `typing.Optional`. (`T | None` for python 3.10+)\n- string value of `Annotated` is used as a description\n- enum value of `Annotated` is used as an enum schema\n\n```python\nimport json\nfrom function_schema import get_function_schema\n\nschema = get_function_schema(get_weather)\nprint(json.dumps(schema, indent=2))\n```\n\nWill output:\n\n```json\n{\n \"name\": \"get_weather\",\n \"description\": \"Returns the weather for the given city.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"city\": {\n \"type\": \"string\",\n \"description\": \"The city to get the weather for\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"description\": \"The unit to return the temperature in\",\n \"enum\": [\n \"celcius\",\n \"fahrenheit\"\n ],\n \"default\": \"celcius\"\n }\n },\n }\n \"required\": [\n \"city\"\n ]\n}\n```\n\nfor claude, you should pass 2nd argument as SchemaFormat.claude or `claude`:\n\n```python\nfrom function_schema import get_function_schema\n\nschema = get_function_schema(get_weather, \"claude\")\n```\n\nPlease refer to the [Claude tool use](https://docs.anthropic.com/claude/docs/tool-use) documentation for more information.\n\nYou can use this schema to make a function call in OpenAI API:\n```python\nimport openai\nopenai.api_key = \"sk-...\"\n\n# Create an assistant with the function\nassistant = client.beta.assistants.create(\n instructions=\"You are a weather bot. Use the provided functions to answer questions.\",\n model=\"gpt-4-turbo-preview\",\n tools=[{\n \"type\": \"function\",\n \"function\": get_function_schema(get_weather),\n }]\n)\n\nrun = client.beta.messages.create(\n assistant_id=assistant.id,\n messages=[\n {\"role\": \"user\", \"content\": \"What's the weather like in Seoul?\"}\n ]\n)\n\n# or with chat completion\n\nresult = openai.chat.completion.create(\n model=\"gpt-3.5-turbo\",\n messages=[\n {\"role\": \"user\", \"content\": \"What's the weather like in Seoul?\"}\n ],\n tools=[get_function_schema(get_weather)],\n tool_call=\"auto\",\n)\n```\n\nIn claude api,\n\n```python\nimport anthropic\n\nclient = anthropic.Client()\n\nresponse = client.beta.tools.messages.create(\n model=\"claude-3-opus-20240229\",\n max_tokens=4096,\n tools=[get_function_schema(get_weather, \"claude\")],\n messages=[\n {\"role\": \"user\", \"content\": \"What's the weather like in Seoul?\"}\n ]\n)\n```\n\n### CLI usage\n\n```sh\nfunction_schema mymodule.py my_function\n```\n\n## License\nMIT License\n",
"bugtrack_url": null,
"license": null,
"summary": "A small utility to generate JSON schemas for python functions.",
"version": "0.3.4",
"project_urls": {
"Homepage": "https://github.com/comfuture/function-schema",
"Repository": "https://github.com/comfuture/function-schema"
},
"split_keywords": [
"json-schema",
" function",
" documentation",
" openai",
" utility"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5049128514b569197393e9e452934c289381813f6c28ec1f993c529382a71319",
"md5": "d38d612f7839fcde781f837fd187c3da",
"sha256": "141cd1eed4e0e294d407b0e0c8d9afe629e7de762284adf190f8fb05ef53f06d"
},
"downloads": -1,
"filename": "function_schema-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d38d612f7839fcde781f837fd187c3da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 5809,
"upload_time": "2024-04-13T09:20:29",
"upload_time_iso_8601": "2024-04-13T09:20:29.329369Z",
"url": "https://files.pythonhosted.org/packages/50/49/128514b569197393e9e452934c289381813f6c28ec1f993c529382a71319/function_schema-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "421700ea1ad99c97b96c3b25a2c3accc7288ced382113ba503fab9074a4ba653",
"md5": "5d73c8c4c56665d4d501bbdb65bcee37",
"sha256": "7ec1bf6532d66f74d16ae47407cf5a8be5563f6b21575fbf011eba5e928d63af"
},
"downloads": -1,
"filename": "function_schema-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "5d73c8c4c56665d4d501bbdb65bcee37",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 4610,
"upload_time": "2024-04-13T09:20:30",
"upload_time_iso_8601": "2024-04-13T09:20:30.866087Z",
"url": "https://files.pythonhosted.org/packages/42/17/00ea1ad99c97b96c3b25a2c3accc7288ced382113ba503fab9074a4ba653/function_schema-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-13 09:20:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "comfuture",
"github_project": "function-schema",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "function-schema"
}
JSON
