schemez 2.2.29__tar.gz → 2.2.30__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- schemez-2.2.30/PKG-INFO +280 -0
- schemez-2.2.30/README.md +226 -0
- schemez-2.2.30/pyproject.toml +318 -0
- schemez-2.2.29/pyproject.toml → schemez-2.2.30/pyproject.toml.orig +28 -16
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/route_helpers.py +6 -8
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/tool_code_generator.py +2 -2
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/commented_yaml.py +4 -4
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/convert.py +7 -8
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/docstrings.py +3 -3
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/__init__.py +0 -1
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/executable.py +19 -15
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/functionschema.py +15 -13
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/helpers.py +1 -1
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/typedefs.py +1 -1
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/generators.py +8 -8
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/helpers.py +4 -4
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/markdown.py +2 -2
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/openapi/callable_factory.py +2 -2
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/openapi/resolver.py +3 -3
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema.py +10 -6
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema_to_type/main_impl.py +2 -2
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema_to_type/marvin_impl.py +16 -16
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema_to_type/simple_impl.py +9 -11
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schemadef/schemadef.py +8 -11
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/storage/model_store.py +5 -3
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/tool_executor/executor.py +5 -4
- schemez-2.2.29/PKG-INFO +0 -496
- schemez-2.2.29/README.md +0 -448
- {schemez-2.2.29 → schemez-2.2.30}/LICENSE +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/__init__.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/bind_kwargs.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/__init__.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/namespace_callable.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/toolset_code_generator.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/schema_generators.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/log.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/openapi/__init__.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/openapi/loader.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/py.typed +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/pydantic_types.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema_to_type/__init__.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schemadef/__init__.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/storage/__init__.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/tool_executor/__init__.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/tool_executor/helpers.py +0 -0
- {schemez-2.2.29 → schemez-2.2.30}/src/schemez/tool_executor/types.py +0 -0
schemez-2.2.30/PKG-INFO
ADDED
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: schemez
|
|
3
|
+
Version: 2.2.30
|
|
4
|
+
Summary: Pydantic toolkit for function schemas, JSON Schema to model conversion, tool code generation and config models
|
|
5
|
+
Keywords: code-generation,configuration,data-models,function-calling,json-schema,llm,openai,pydantic,schema,serialization,tool-use,type-hints,validation,yaml
|
|
6
|
+
Author: Philipp Temminghoff
|
|
7
|
+
Author-email: Philipp Temminghoff <philipptemminghoff@googlemail.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Framework :: Pydantic
|
|
12
|
+
Classifier: Framework :: Pydantic :: 2
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Topic :: Software Development
|
|
20
|
+
Classifier: Topic :: Software Development :: Code Generators
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
+
Classifier: Topic :: Utilities
|
|
23
|
+
Classifier: Typing :: Typed
|
|
24
|
+
Requires-Dist: docstring-parser>=0.17.0
|
|
25
|
+
Requires-Dist: griffelib
|
|
26
|
+
Requires-Dist: pydantic
|
|
27
|
+
Requires-Dist: pydantic-core
|
|
28
|
+
Requires-Dist: typing-extensions>=4.12.0
|
|
29
|
+
Requires-Dist: universal-pathlib>=0.2.6
|
|
30
|
+
Requires-Dist: agentpool ; extra == 'ai'
|
|
31
|
+
Requires-Dist: anyenv>=0.4.14 ; extra == 'ai'
|
|
32
|
+
Requires-Dist: httpx>=0.27.0 ; extra == 'ai'
|
|
33
|
+
Requires-Dist: pydantic-ai-slim>=1.0.0 ; extra == 'ai'
|
|
34
|
+
Requires-Dist: datamodel-code-generator[ruff] ; extra == 'codegen'
|
|
35
|
+
Requires-Dist: jinja2>=3.1.0 ; extra == 'markdown'
|
|
36
|
+
Requires-Dist: aiosqlite>=0.20.0 ; extra == 'storage'
|
|
37
|
+
Requires-Dist: fastapi>=0.118.2 ; extra == 'tool-execution'
|
|
38
|
+
Requires-Dist: uvicorn>=0.30.0 ; extra == 'tool-execution'
|
|
39
|
+
Requires-Dist: yamling ; extra == 'yaml'
|
|
40
|
+
Requires-Python: >=3.13
|
|
41
|
+
Project-URL: Code coverage, https://app.codecov.io/gh/phil65/schemez
|
|
42
|
+
Project-URL: Discussions, https://github.com/phil65/schemez/discussions
|
|
43
|
+
Project-URL: Documentation, https://phil65.github.io/schemez/
|
|
44
|
+
Project-URL: Homepage, https://github.com/phil65/schemez
|
|
45
|
+
Project-URL: Issues, https://github.com/phil65/schemez/issues
|
|
46
|
+
Project-URL: Source, https://github.com/phil65/schemez
|
|
47
|
+
Provides-Extra: ai
|
|
48
|
+
Provides-Extra: codegen
|
|
49
|
+
Provides-Extra: markdown
|
|
50
|
+
Provides-Extra: storage
|
|
51
|
+
Provides-Extra: tool-execution
|
|
52
|
+
Provides-Extra: yaml
|
|
53
|
+
Description-Content-Type: text/markdown
|
|
54
|
+
|
|
55
|
+
# Schemez
|
|
56
|
+
|
|
57
|
+
[](https://pypi.org/project/schemez/)
|
|
58
|
+
[](https://pypi.org/project/schemez/)
|
|
59
|
+
[](https://pypi.org/project/schemez/)
|
|
60
|
+
[](https://pypi.org/project/schemez/)
|
|
61
|
+
[](https://pypi.org/project/schemez/)
|
|
62
|
+
[](https://pypi.org/project/schemez/)
|
|
63
|
+
[](https://pypi.org/project/schemez/)
|
|
64
|
+
[](https://github.com/phil65/schemez/releases)
|
|
65
|
+
[](https://github.com/phil65/schemez/graphs/contributors)
|
|
66
|
+
[](https://github.com/phil65/schemez/discussions)
|
|
67
|
+
[](https://github.com/phil65/schemez/forks)
|
|
68
|
+
[](https://github.com/phil65/schemez/issues)
|
|
69
|
+
[](https://github.com/phil65/schemez/pulls)
|
|
70
|
+
[](https://github.com/phil65/schemez/watchers)
|
|
71
|
+
[](https://github.com/phil65/schemez/stars)
|
|
72
|
+
[](https://github.com/phil65/schemez)
|
|
73
|
+
[](https://github.com/phil65/schemez/commits)
|
|
74
|
+
[](https://github.com/phil65/schemez/releases)
|
|
75
|
+
[](https://github.com/phil65/schemez)
|
|
76
|
+
[](https://github.com/phil65/schemez)
|
|
77
|
+
[](https://codecov.io/gh/phil65/schemez/)
|
|
78
|
+
[](https://pyup.io/repos/github/phil65/schemez/)
|
|
79
|
+
|
|
80
|
+
[Read the documentation!](https://phil65.github.io/schemez/)
|
|
81
|
+
|
|
82
|
+
Schemez is a Pydantic toolkit for turning Python code into schemas and schemas into code.
|
|
83
|
+
It builds OpenAI-compatible tool schemas from function signatures, creates Pydantic models
|
|
84
|
+
from JSON Schema, generates HTTP/MCP client code and FastAPI routes for tools, and gives your
|
|
85
|
+
config models YAML, markdown and test-data helpers.
|
|
86
|
+
|
|
87
|
+
## Installation
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
pip install schemez
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Optional extras enable individual features:
|
|
94
|
+
|
|
95
|
+
| Extra | Enables |
|
|
96
|
+
| --- | --- |
|
|
97
|
+
| `yaml` | `Schema.from_yaml()`, `Schema.model_dump_yaml()` |
|
|
98
|
+
| `codegen` | `Schema.from_json_schema()`, `FunctionSchema.to_parameter_model_code()`, `jsonschema_to_code()`, `openapi_to_code()` |
|
|
99
|
+
| `tool_execution` | FastAPI routes and the HTTP tool server |
|
|
100
|
+
| `storage` | `ModelStore` (async SQLite storage) |
|
|
101
|
+
| `markdown` | Jinja templates for markdown docs |
|
|
102
|
+
| `ai` | `Schema.from_llm()`, `create_schema(..., mode="openai")`, `schemez.openapi` |
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
pip install "schemez[yaml,codegen]"
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Quick start
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
from typing import Literal
|
|
112
|
+
|
|
113
|
+
from schemez import create_schema
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def search_users(
|
|
117
|
+
query: str,
|
|
118
|
+
limit: int = 10,
|
|
119
|
+
status: Literal["active", "inactive"] = "active",
|
|
120
|
+
) -> list[dict]:
|
|
121
|
+
"""Search for users.
|
|
122
|
+
|
|
123
|
+
Args:
|
|
124
|
+
query: Search query string
|
|
125
|
+
limit: Maximum number of results
|
|
126
|
+
status: User status filter
|
|
127
|
+
"""
|
|
128
|
+
return []
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
schema = create_schema(search_users)
|
|
132
|
+
schema.name # "search_users"
|
|
133
|
+
schema.description # "Search for users."
|
|
134
|
+
schema.parameters["properties"]["status"]
|
|
135
|
+
# {'type': 'string', 'description': 'User status filter',
|
|
136
|
+
# 'enum': ['active', 'inactive'], 'default': 'active'}
|
|
137
|
+
|
|
138
|
+
schema.model_dump_openai() # {"type": "function", "function": {...}}
|
|
139
|
+
schema.to_python_signature()
|
|
140
|
+
# (*, query: str, limit: int = 10, status: Literal['active', 'inactive'] = 'active') -> list[typing.Any]
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## Features
|
|
144
|
+
|
|
145
|
+
### Function schemas
|
|
146
|
+
|
|
147
|
+
`create_schema()` returns a `FunctionSchema` (name, description, parameters, required, returns)
|
|
148
|
+
built from type hints and docstrings (Google, NumPy and Sphinx styles).
|
|
149
|
+
|
|
150
|
+
- `model_dump_openai()`: OpenAI function-calling tool definition
|
|
151
|
+
- `to_python_signature()`, `get_annotations()`: reconstruct the signature
|
|
152
|
+
- `create_parameter_model()`: Pydantic model for the parameters
|
|
153
|
+
- `to_parameter_model_code()` / `to_return_model_code()`: Python source for those models (`codegen` extra)
|
|
154
|
+
- `create_schema(func, exclude_types=[Context])` drops parameters of the given types (e.g. injected
|
|
155
|
+
context objects); `name_override` / `description_override` replace name and docstring.
|
|
156
|
+
- `mode="simple"` (default) produces compact, LLM-friendly schemas: unions collapse to their first
|
|
157
|
+
type, enums become plain value lists. `mode="jsonschema"` keeps Pydantic's full JSON Schema
|
|
158
|
+
(`anyOf`, `$defs`), `mode="openai"` uses pydantic-ai's tool schema generator.
|
|
159
|
+
|
|
160
|
+
Bulk helpers: `create_schemas_from_callables({"name": func, ...})`, `create_schemas_from_class(cls)`,
|
|
161
|
+
`create_schemas_from_module(module, include_functions=[...])` and `create_constructor_schema(cls)`.
|
|
162
|
+
|
|
163
|
+
`create_executable(func)` wraps a function together with its schema and runs sync, async and
|
|
164
|
+
(async) generator functions uniformly via `run()`, `arun()` and `astream()`.
|
|
165
|
+
|
|
166
|
+
### `Schema` base model
|
|
167
|
+
|
|
168
|
+
`Schema` is a `pydantic.BaseModel` with `extra="forbid"` and attribute docstrings as field
|
|
169
|
+
descriptions, plus helpers:
|
|
170
|
+
|
|
171
|
+
```python
|
|
172
|
+
from schemez import Schema
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
class DatabaseConfig(Schema):
|
|
176
|
+
host: str = "localhost"
|
|
177
|
+
"""Database host."""
|
|
178
|
+
|
|
179
|
+
port: int = 5432
|
|
180
|
+
"""Database port."""
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
class AppConfig(Schema):
|
|
184
|
+
name: str
|
|
185
|
+
database: DatabaseConfig = DatabaseConfig()
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
config = AppConfig.from_yaml("name: my-app\ndatabase:\n port: 6543\n")
|
|
189
|
+
print(config.model_dump_yaml(comments=True))
|
|
190
|
+
# database:
|
|
191
|
+
# host: localhost # Database host.
|
|
192
|
+
# port: 6543 # Database port.
|
|
193
|
+
# name: my-app
|
|
194
|
+
|
|
195
|
+
config.model_dump_markdown() # markdown table documenting the model and its values
|
|
196
|
+
AppConfig.generate_test_data(mode="minimal") # valid instance generated from the schema
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
More class methods: `Schema.for_function(func)` and `Schema.for_class_ctor(cls)` build models from
|
|
200
|
+
signatures, `Schema.from_json_schema(json_schema)` builds one from JSON Schema (`codegen` extra),
|
|
201
|
+
`to_python_code()` emits model source code, and `merge()` / `iter_submodels()` work on instances.
|
|
202
|
+
|
|
203
|
+
### JSON Schema and OpenAPI to code
|
|
204
|
+
|
|
205
|
+
`jsonschema_to_code()` and `openapi_to_code()` generate Pydantic model source code (via
|
|
206
|
+
datamodel-code-generator). `SchemaDef` (`InlineSchemaDef`, `ImportedSchemaDef`) lets you declare
|
|
207
|
+
models in YAML/JSON config and build them with `get_schema()`.
|
|
208
|
+
|
|
209
|
+
### Tool code generation
|
|
210
|
+
|
|
211
|
+
`ToolsetCodeGenerator` turns a set of callables (or `FunctionSchema`s) into client code, LLM stubs
|
|
212
|
+
or FastAPI routes:
|
|
213
|
+
|
|
214
|
+
```python
|
|
215
|
+
from fastapi import FastAPI
|
|
216
|
+
|
|
217
|
+
from schemez import ToolsetCodeGenerator
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def get_weather(location: str, unit: str = "C") -> dict:
|
|
221
|
+
"""Get weather for a location."""
|
|
222
|
+
return {"temp": 22, "location": location}
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
generator = ToolsetCodeGenerator.from_callables([get_weather, search_users])
|
|
226
|
+
|
|
227
|
+
# Async httpx client functions calling a tool server
|
|
228
|
+
client_code = generator.generate_code(base_url="https://api.example.com", path_prefix="/tools")
|
|
229
|
+
# Signatures + docstrings only, for LLM prompts
|
|
230
|
+
stubs = generator.generate_code(output_type="stubs")
|
|
231
|
+
# Functions taking a generated Pydantic input model instead of keyword arguments
|
|
232
|
+
model_based = generator.generate_code(args_format="model")
|
|
233
|
+
# Human-readable overview of the available functions
|
|
234
|
+
print(generator.generate_tool_description())
|
|
235
|
+
|
|
236
|
+
# Expose the callables as FastAPI routes: GET /tools/get_weather, GET /tools/search_users
|
|
237
|
+
app = FastAPI()
|
|
238
|
+
generator.add_all_routes(app, path_prefix="/tools")
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
`ToolsetCodeGenerator.from_schemas([...])` works without implementations (code generation only),
|
|
242
|
+
`generate_mcp_code(server_configs)` emits FastMCP client code, and `ToolCodeGenerator` handles a
|
|
243
|
+
single tool. `schemez.tool_executor.HttpToolExecutor` serves tools over HTTP.
|
|
244
|
+
|
|
245
|
+
### Model storage
|
|
246
|
+
|
|
247
|
+
```python
|
|
248
|
+
from pydantic import BaseModel
|
|
249
|
+
|
|
250
|
+
from schemez import ModelStore
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
class Note(BaseModel):
|
|
254
|
+
title: str
|
|
255
|
+
tags: list[str] = []
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
async def main() -> None:
|
|
259
|
+
async with ModelStore(Note, "notes.db") as store:
|
|
260
|
+
note_id = await store.insert(Note(title="hello", tags=["a"]))
|
|
261
|
+
await store.get(note_id) # Note(title='hello', tags=['a'])
|
|
262
|
+
await store.query(title="hello")
|
|
263
|
+
|
|
264
|
+
# Reopen later: the model type is rebuilt from the stored JSON schema
|
|
265
|
+
async with await ModelStore.open("notes.db") as store:
|
|
266
|
+
await store.all()
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### Markdown documentation
|
|
270
|
+
|
|
271
|
+
`models_to_markdown_docs()` renders documentation for several models; the `jinjarope` entry point
|
|
272
|
+
registers the markdown helpers as Jinja filters.
|
|
273
|
+
|
|
274
|
+
## Documentation
|
|
275
|
+
|
|
276
|
+
Full API reference: https://phil65.github.io/schemez/
|
|
277
|
+
|
|
278
|
+
## License
|
|
279
|
+
|
|
280
|
+
MIT
|
schemez-2.2.30/README.md
ADDED
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
# Schemez
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/schemez/)
|
|
4
|
+
[](https://pypi.org/project/schemez/)
|
|
5
|
+
[](https://pypi.org/project/schemez/)
|
|
6
|
+
[](https://pypi.org/project/schemez/)
|
|
7
|
+
[](https://pypi.org/project/schemez/)
|
|
8
|
+
[](https://pypi.org/project/schemez/)
|
|
9
|
+
[](https://pypi.org/project/schemez/)
|
|
10
|
+
[](https://github.com/phil65/schemez/releases)
|
|
11
|
+
[](https://github.com/phil65/schemez/graphs/contributors)
|
|
12
|
+
[](https://github.com/phil65/schemez/discussions)
|
|
13
|
+
[](https://github.com/phil65/schemez/forks)
|
|
14
|
+
[](https://github.com/phil65/schemez/issues)
|
|
15
|
+
[](https://github.com/phil65/schemez/pulls)
|
|
16
|
+
[](https://github.com/phil65/schemez/watchers)
|
|
17
|
+
[](https://github.com/phil65/schemez/stars)
|
|
18
|
+
[](https://github.com/phil65/schemez)
|
|
19
|
+
[](https://github.com/phil65/schemez/commits)
|
|
20
|
+
[](https://github.com/phil65/schemez/releases)
|
|
21
|
+
[](https://github.com/phil65/schemez)
|
|
22
|
+
[](https://github.com/phil65/schemez)
|
|
23
|
+
[](https://codecov.io/gh/phil65/schemez/)
|
|
24
|
+
[](https://pyup.io/repos/github/phil65/schemez/)
|
|
25
|
+
|
|
26
|
+
[Read the documentation!](https://phil65.github.io/schemez/)
|
|
27
|
+
|
|
28
|
+
Schemez is a Pydantic toolkit for turning Python code into schemas and schemas into code.
|
|
29
|
+
It builds OpenAI-compatible tool schemas from function signatures, creates Pydantic models
|
|
30
|
+
from JSON Schema, generates HTTP/MCP client code and FastAPI routes for tools, and gives your
|
|
31
|
+
config models YAML, markdown and test-data helpers.
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install schemez
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Optional extras enable individual features:
|
|
40
|
+
|
|
41
|
+
| Extra | Enables |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `yaml` | `Schema.from_yaml()`, `Schema.model_dump_yaml()` |
|
|
44
|
+
| `codegen` | `Schema.from_json_schema()`, `FunctionSchema.to_parameter_model_code()`, `jsonschema_to_code()`, `openapi_to_code()` |
|
|
45
|
+
| `tool_execution` | FastAPI routes and the HTTP tool server |
|
|
46
|
+
| `storage` | `ModelStore` (async SQLite storage) |
|
|
47
|
+
| `markdown` | Jinja templates for markdown docs |
|
|
48
|
+
| `ai` | `Schema.from_llm()`, `create_schema(..., mode="openai")`, `schemez.openapi` |
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pip install "schemez[yaml,codegen]"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Quick start
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from typing import Literal
|
|
58
|
+
|
|
59
|
+
from schemez import create_schema
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def search_users(
|
|
63
|
+
query: str,
|
|
64
|
+
limit: int = 10,
|
|
65
|
+
status: Literal["active", "inactive"] = "active",
|
|
66
|
+
) -> list[dict]:
|
|
67
|
+
"""Search for users.
|
|
68
|
+
|
|
69
|
+
Args:
|
|
70
|
+
query: Search query string
|
|
71
|
+
limit: Maximum number of results
|
|
72
|
+
status: User status filter
|
|
73
|
+
"""
|
|
74
|
+
return []
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
schema = create_schema(search_users)
|
|
78
|
+
schema.name # "search_users"
|
|
79
|
+
schema.description # "Search for users."
|
|
80
|
+
schema.parameters["properties"]["status"]
|
|
81
|
+
# {'type': 'string', 'description': 'User status filter',
|
|
82
|
+
# 'enum': ['active', 'inactive'], 'default': 'active'}
|
|
83
|
+
|
|
84
|
+
schema.model_dump_openai() # {"type": "function", "function": {...}}
|
|
85
|
+
schema.to_python_signature()
|
|
86
|
+
# (*, query: str, limit: int = 10, status: Literal['active', 'inactive'] = 'active') -> list[typing.Any]
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Features
|
|
90
|
+
|
|
91
|
+
### Function schemas
|
|
92
|
+
|
|
93
|
+
`create_schema()` returns a `FunctionSchema` (name, description, parameters, required, returns)
|
|
94
|
+
built from type hints and docstrings (Google, NumPy and Sphinx styles).
|
|
95
|
+
|
|
96
|
+
- `model_dump_openai()`: OpenAI function-calling tool definition
|
|
97
|
+
- `to_python_signature()`, `get_annotations()`: reconstruct the signature
|
|
98
|
+
- `create_parameter_model()`: Pydantic model for the parameters
|
|
99
|
+
- `to_parameter_model_code()` / `to_return_model_code()`: Python source for those models (`codegen` extra)
|
|
100
|
+
- `create_schema(func, exclude_types=[Context])` drops parameters of the given types (e.g. injected
|
|
101
|
+
context objects); `name_override` / `description_override` replace name and docstring.
|
|
102
|
+
- `mode="simple"` (default) produces compact, LLM-friendly schemas: unions collapse to their first
|
|
103
|
+
type, enums become plain value lists. `mode="jsonschema"` keeps Pydantic's full JSON Schema
|
|
104
|
+
(`anyOf`, `$defs`), `mode="openai"` uses pydantic-ai's tool schema generator.
|
|
105
|
+
|
|
106
|
+
Bulk helpers: `create_schemas_from_callables({"name": func, ...})`, `create_schemas_from_class(cls)`,
|
|
107
|
+
`create_schemas_from_module(module, include_functions=[...])` and `create_constructor_schema(cls)`.
|
|
108
|
+
|
|
109
|
+
`create_executable(func)` wraps a function together with its schema and runs sync, async and
|
|
110
|
+
(async) generator functions uniformly via `run()`, `arun()` and `astream()`.
|
|
111
|
+
|
|
112
|
+
### `Schema` base model
|
|
113
|
+
|
|
114
|
+
`Schema` is a `pydantic.BaseModel` with `extra="forbid"` and attribute docstrings as field
|
|
115
|
+
descriptions, plus helpers:
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
from schemez import Schema
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
class DatabaseConfig(Schema):
|
|
122
|
+
host: str = "localhost"
|
|
123
|
+
"""Database host."""
|
|
124
|
+
|
|
125
|
+
port: int = 5432
|
|
126
|
+
"""Database port."""
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
class AppConfig(Schema):
|
|
130
|
+
name: str
|
|
131
|
+
database: DatabaseConfig = DatabaseConfig()
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
config = AppConfig.from_yaml("name: my-app\ndatabase:\n port: 6543\n")
|
|
135
|
+
print(config.model_dump_yaml(comments=True))
|
|
136
|
+
# database:
|
|
137
|
+
# host: localhost # Database host.
|
|
138
|
+
# port: 6543 # Database port.
|
|
139
|
+
# name: my-app
|
|
140
|
+
|
|
141
|
+
config.model_dump_markdown() # markdown table documenting the model and its values
|
|
142
|
+
AppConfig.generate_test_data(mode="minimal") # valid instance generated from the schema
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
More class methods: `Schema.for_function(func)` and `Schema.for_class_ctor(cls)` build models from
|
|
146
|
+
signatures, `Schema.from_json_schema(json_schema)` builds one from JSON Schema (`codegen` extra),
|
|
147
|
+
`to_python_code()` emits model source code, and `merge()` / `iter_submodels()` work on instances.
|
|
148
|
+
|
|
149
|
+
### JSON Schema and OpenAPI to code
|
|
150
|
+
|
|
151
|
+
`jsonschema_to_code()` and `openapi_to_code()` generate Pydantic model source code (via
|
|
152
|
+
datamodel-code-generator). `SchemaDef` (`InlineSchemaDef`, `ImportedSchemaDef`) lets you declare
|
|
153
|
+
models in YAML/JSON config and build them with `get_schema()`.
|
|
154
|
+
|
|
155
|
+
### Tool code generation
|
|
156
|
+
|
|
157
|
+
`ToolsetCodeGenerator` turns a set of callables (or `FunctionSchema`s) into client code, LLM stubs
|
|
158
|
+
or FastAPI routes:
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
from fastapi import FastAPI
|
|
162
|
+
|
|
163
|
+
from schemez import ToolsetCodeGenerator
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def get_weather(location: str, unit: str = "C") -> dict:
|
|
167
|
+
"""Get weather for a location."""
|
|
168
|
+
return {"temp": 22, "location": location}
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
generator = ToolsetCodeGenerator.from_callables([get_weather, search_users])
|
|
172
|
+
|
|
173
|
+
# Async httpx client functions calling a tool server
|
|
174
|
+
client_code = generator.generate_code(base_url="https://api.example.com", path_prefix="/tools")
|
|
175
|
+
# Signatures + docstrings only, for LLM prompts
|
|
176
|
+
stubs = generator.generate_code(output_type="stubs")
|
|
177
|
+
# Functions taking a generated Pydantic input model instead of keyword arguments
|
|
178
|
+
model_based = generator.generate_code(args_format="model")
|
|
179
|
+
# Human-readable overview of the available functions
|
|
180
|
+
print(generator.generate_tool_description())
|
|
181
|
+
|
|
182
|
+
# Expose the callables as FastAPI routes: GET /tools/get_weather, GET /tools/search_users
|
|
183
|
+
app = FastAPI()
|
|
184
|
+
generator.add_all_routes(app, path_prefix="/tools")
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
`ToolsetCodeGenerator.from_schemas([...])` works without implementations (code generation only),
|
|
188
|
+
`generate_mcp_code(server_configs)` emits FastMCP client code, and `ToolCodeGenerator` handles a
|
|
189
|
+
single tool. `schemez.tool_executor.HttpToolExecutor` serves tools over HTTP.
|
|
190
|
+
|
|
191
|
+
### Model storage
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
from pydantic import BaseModel
|
|
195
|
+
|
|
196
|
+
from schemez import ModelStore
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
class Note(BaseModel):
|
|
200
|
+
title: str
|
|
201
|
+
tags: list[str] = []
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
async def main() -> None:
|
|
205
|
+
async with ModelStore(Note, "notes.db") as store:
|
|
206
|
+
note_id = await store.insert(Note(title="hello", tags=["a"]))
|
|
207
|
+
await store.get(note_id) # Note(title='hello', tags=['a'])
|
|
208
|
+
await store.query(title="hello")
|
|
209
|
+
|
|
210
|
+
# Reopen later: the model type is rebuilt from the stored JSON schema
|
|
211
|
+
async with await ModelStore.open("notes.db") as store:
|
|
212
|
+
await store.all()
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### Markdown documentation
|
|
216
|
+
|
|
217
|
+
`models_to_markdown_docs()` renders documentation for several models; the `jinjarope` entry point
|
|
218
|
+
registers the markdown helpers as Jinja filters.
|
|
219
|
+
|
|
220
|
+
## Documentation
|
|
221
|
+
|
|
222
|
+
Full API reference: https://phil65.github.io/schemez/
|
|
223
|
+
|
|
224
|
+
## License
|
|
225
|
+
|
|
226
|
+
MIT
|