# 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 Tool 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 Tool 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
from function_schema import Doc
import enum
def get_weather(
city: Annotated[str, Doc("The city to get the weather for")],
unit: Annotated[
Optional[str],
Doc("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.
Then you can generate a schema for this function:
```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 any type hinting supported by python for the first argument of `Annotated`. including:
`typing.Literal`, `typing.Optional`, `typing.Union`, and `T | None` for python 3.10+.
`Doc` class or plain string in `Annotated` is used for describe the parameter.
`Doc` metadata is the [PEP propose](https://peps.python.org/pep-0727/) for standardizing the metadata in type hints.
currently, implemented in `typing-extensions` module. Also `function_schema.Doc` is provided for compatibility.
Enumeratable candidates can be defined with `enum.Enum` in the argument of `Annotated`.
```python
import enum
class AnimalType(enum.Enum):
dog = enum.auto()
cat = enum.auto()
def get_animal(
animal: Annotated[str, Doc("The animal to get"), AnimalType],
) -> str:
"""Returns the animal."""
return f"Animal is {animal.value}"
```
In this example, each name of `AnimalType` enums(`dog`, `cat`) is used as an enum schema.
In shorthand, you can use `typing.Literal` as the type will do the same thing.
```python
def get_animal(
animal: Annotated[Literal["dog", "cat"], Doc("The animal to get")],
) -> str:
"""Returns the animal."""
return f"Animal is {animal}"
```
### Plain String in Annotated
The string value of `Annotated` is used as a description for convenience.
```python
def get_weather(
city: Annotated[str, "The city to get the weather for"], # <- string value of Annotated is used as a description
unit: Annotated[Optional[str], "The unit to return the temperature in"] = "celcius",
) -> str:
"""Returns the weather for the given city."""
return f"Weather for {city} is 20°C"
```
But this would create a predefined meaning for any plain string inside of `Annotated`,
and any tool that was using plain strings in them for any other purpose, which is currently allowed, would now be invalid.
Please refer to the [PEP 0727, Plain String in Annotated](https://peps.python.org/pep-0727/#plain-string-in-annotated) for more information.
### Usage with OpenAI API
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=[{
"type": "function",
"function": get_function_schema(get_weather)
}],
tool_call="auto",
)
```
### Usage with Anthropic Claude
```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 | jq
```
## 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/da/83/33bee8379ffddc40d2974440945c6014947ad5a424a72157b0b4e3491609/function_schema-0.4.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 Tool 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 Tool 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\nfrom function_schema import Doc\nimport enum\n\ndef get_weather(\n city: Annotated[str, Doc(\"The city to get the weather for\")],\n unit: Annotated[\n Optional[str],\n Doc(\"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\nThen you can generate a schema for this function:\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 any type hinting supported by python for the first argument of `Annotated`. including:\n`typing.Literal`, `typing.Optional`, `typing.Union`, and `T | None` for python 3.10+. \n`Doc` class or plain string in `Annotated` is used for describe the parameter.\n`Doc` metadata is the [PEP propose](https://peps.python.org/pep-0727/) for standardizing the metadata in type hints.\ncurrently, implemented in `typing-extensions` module. Also `function_schema.Doc` is provided for compatibility.\n\nEnumeratable candidates can be defined with `enum.Enum` in the argument of `Annotated`.\n\n```python\nimport enum\n\nclass AnimalType(enum.Enum):\n dog = enum.auto()\n cat = enum.auto()\n\ndef get_animal(\n animal: Annotated[str, Doc(\"The animal to get\"), AnimalType],\n) -> str:\n \"\"\"Returns the animal.\"\"\"\n return f\"Animal is {animal.value}\"\n```\nIn this example, each name of `AnimalType` enums(`dog`, `cat`) is used as an enum schema.\nIn shorthand, you can use `typing.Literal` as the type will do the same thing.\n\n```python\ndef get_animal(\n animal: Annotated[Literal[\"dog\", \"cat\"], Doc(\"The animal to get\")],\n) -> str:\n \"\"\"Returns the animal.\"\"\"\n return f\"Animal is {animal}\"\n```\n\n\n### Plain String in Annotated\n\nThe string value of `Annotated` is used as a description for convenience.\n\n```python\ndef get_weather(\n city: Annotated[str, \"The city to get the weather for\"], # <- string value of Annotated is used as a description\n unit: Annotated[Optional[str], \"The unit to return the temperature in\"] = \"celcius\",\n) -> str:\n \"\"\"Returns the weather for the given city.\"\"\"\n return f\"Weather for {city} is 20\u00b0C\"\n```\n\nBut this would create a predefined meaning for any plain string inside of `Annotated`,\nand any tool that was using plain strings in them for any other purpose, which is currently allowed, would now be invalid.\nPlease refer to the [PEP 0727, Plain String in Annotated](https://peps.python.org/pep-0727/#plain-string-in-annotated) for more information.\n\n### Usage with OpenAI API\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=[{\n \"type\": \"function\",\n \"function\": get_function_schema(get_weather)\n }],\n tool_call=\"auto\",\n)\n```\n\n### Usage with Anthropic Claude\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 | jq\n```\n\n## License\nMIT License\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A small utility to generate JSON schemas for python functions.",
"version": "0.4.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": "1594edfe7cd0c804032c37e8499e539ed4c790803d7a4cd400a291ab7ed60595",
"md5": "8f08ed043f4037503e37076a92859c18",
"sha256": "fb735bfad77f531650ea857d9ea31437dec1053045f7078d8e2b8483583515fa"
},
"downloads": -1,
"filename": "function_schema-0.4.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8f08ed043f4037503e37076a92859c18",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7759,
"upload_time": "2024-09-27T08:06:01",
"upload_time_iso_8601": "2024-09-27T08:06:01.137524Z",
"url": "https://files.pythonhosted.org/packages/15/94/edfe7cd0c804032c37e8499e539ed4c790803d7a4cd400a291ab7ed60595/function_schema-0.4.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "da8333bee8379ffddc40d2974440945c6014947ad5a424a72157b0b4e3491609",
"md5": "950a727c9975d4f5e38822c7902147ba",
"sha256": "4649808f68d3529bf6088b9d6b52e2ec46b344ea584efe56636958b18af890e8"
},
"downloads": -1,
"filename": "function_schema-0.4.4.tar.gz",
"has_sig": false,
"md5_digest": "950a727c9975d4f5e38822c7902147ba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6047,
"upload_time": "2024-09-27T08:06:02",
"upload_time_iso_8601": "2024-09-27T08:06:02.122241Z",
"url": "https://files.pythonhosted.org/packages/da/83/33bee8379ffddc40d2974440945c6014947ad5a424a72157b0b4e3491609/function_schema-0.4.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-27 08:06:02",
"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
