structured-llm 0.1.0__tar.gz

structured_llm-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# tmp
+sample
+.mypy_cache
+.ruff_cache
+
+# Virtual environments
+.venv
+
+# env
+.env

structured_llm-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

structured_llm-0.1.0/Makefile

@@ -0,0 +1,16 @@
+.PHONY: setup lint test check
+VENV_BIN ?= .venv/bin
+
+setup:
+	@command -v uv >/dev/null 2>&1 || pip install uv --break-system-packages
+	@[ -d .venv ] || uv venv .venv --python 3.13
+	. .venv/bin/activate && uv sync
+
+lint:
+	$(VENV_BIN)/ruff check --fix
+	$(VENV_BIN)/mypy .
+
+test:
+	$(VENV_BIN)/python -m pytest . -q
+
+check: lint test

structured_llm-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: structured-llm
+Version: 0.1.0
+Summary: Lightweight structured output runtime for Python LLM calls.
+Author: structured-llm contributors
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.2.2
+Description-Content-Type: text/markdown
+
+# structured-llm
+
+一个轻量的 Python 结构化输出运行时。
+
+它直接使用 Pydantic 类型作为 schema，不需要 `.baml` 文件、CLI、代码生成，也不需要额外的运行时编译器。默认行为是 BAML 风格的「output format prompt + 本地 JSON 提取/轻量修复 + Pydantic 校验」，因此不依赖特定供应商是否支持 `response_format`。
+
+## 安装依赖
+
+普通运行依赖：
+
+```bash
+uv sync --no-config --default-index https://pypi.org/simple
+```
+
+开发依赖安装在 `dev` dependency group 中，包括 `pytest`、`pytest-asyncio`、`ruff`、`mypy`：
+
+```bash
+uv sync --group dev --no-config --default-index https://pypi.org/simple
+```
+
+如果需要新增开发工具依赖：
+
+```bash
+uv add <package> --group dev --no-config --default-index https://pypi.org/simple
+```
+
+## 使用示例
+
+```python
+from pydantic import BaseModel, Field
+from structured_llm import StructuredClient
+
+
+class Receipt(BaseModel):
+    merchant: str = Field(description="商户或店铺名称")
+    total: float = Field(description="收据最终支付总金额")
+
+
+client = StructuredClient(model="gpt-4o-mini", debug=True)
+receipt = client.run("Extract the receipt: Coffee $4.50", Receipt)
+
+print(receipt.merchant)
+print(receipt.total)
+```
+
+默认 OpenAI-compatible provider 会从 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` 读取配置；如果代码里显式传入 `api_key` 或 `base_url`，会优先使用显式参数。`examples/receipt_extraction.py` 会通过 `python-dotenv` 自动加载本地 `.env`。
+
+`Field(description=...)` 会渲染到默认 output format prompt。`debug=True` 会把传给 OpenAI-compatible SDK 的 request payload 和模型解析前的原始输出打印到 stderr。默认不会发送 `response_format`；只有显式设置 `mode="native"` 或 `mode="auto"` 时才会尝试 provider-native structured output。
+
+只解析已有的 LLM 文本输出：
+
+```python
+raw = """
+```json
+{"merchant": "Coffee Shop", "total": 4.5}
+```
+"""
+
+receipt = client.parse(raw, Receipt)
+```
+
+## 开发命令
+
+运行测试：
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 uv run --no-config --default-index https://pypi.org/simple --group dev python -m pytest -p no:cacheprovider
+```
+
+运行 Ruff：
+
+```bash
+uv run --no-config --default-index https://pypi.org/simple --group dev ruff check .
+```
+
+运行 mypy：
+
+```bash
+uv run --no-config --default-index https://pypi.org/simple --group dev mypy structured_llm
+```
+
+## 当前范围
+
+- 支持同步调用：`StructuredClient.run(...)`
+- 支持异步调用：`StructuredClient.arun(...)`
+- 支持本地解析：`StructuredClient.parse(...)`
+- 支持 Pydantic `BaseModel`、`list[...]`、`dict[...]`、`Literal`、`Enum` 等 `TypeAdapter` 可处理的类型
+- 暂不支持流式 partial object、多 provider 内置适配、BAML DSL/codegen

structured_llm-0.1.0/README.md

@@ -0,0 +1,88 @@
+# structured-llm
+
+一个轻量的 Python 结构化输出运行时。
+
+它直接使用 Pydantic 类型作为 schema，不需要 `.baml` 文件、CLI、代码生成，也不需要额外的运行时编译器。默认行为是 BAML 风格的「output format prompt + 本地 JSON 提取/轻量修复 + Pydantic 校验」，因此不依赖特定供应商是否支持 `response_format`。
+
+## 安装依赖
+
+普通运行依赖：
+
+```bash
+uv sync --no-config --default-index https://pypi.org/simple
+```
+
+开发依赖安装在 `dev` dependency group 中，包括 `pytest`、`pytest-asyncio`、`ruff`、`mypy`：
+
+```bash
+uv sync --group dev --no-config --default-index https://pypi.org/simple
+```
+
+如果需要新增开发工具依赖：
+
+```bash
+uv add <package> --group dev --no-config --default-index https://pypi.org/simple
+```
+
+## 使用示例
+
+```python
+from pydantic import BaseModel, Field
+from structured_llm import StructuredClient
+
+
+class Receipt(BaseModel):
+    merchant: str = Field(description="商户或店铺名称")
+    total: float = Field(description="收据最终支付总金额")
+
+
+client = StructuredClient(model="gpt-4o-mini", debug=True)
+receipt = client.run("Extract the receipt: Coffee $4.50", Receipt)
+
+print(receipt.merchant)
+print(receipt.total)
+```
+
+默认 OpenAI-compatible provider 会从 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` 读取配置；如果代码里显式传入 `api_key` 或 `base_url`，会优先使用显式参数。`examples/receipt_extraction.py` 会通过 `python-dotenv` 自动加载本地 `.env`。
+
+`Field(description=...)` 会渲染到默认 output format prompt。`debug=True` 会把传给 OpenAI-compatible SDK 的 request payload 和模型解析前的原始输出打印到 stderr。默认不会发送 `response_format`；只有显式设置 `mode="native"` 或 `mode="auto"` 时才会尝试 provider-native structured output。
+
+只解析已有的 LLM 文本输出：
+
+```python
+raw = """
+```json
+{"merchant": "Coffee Shop", "total": 4.5}
+```
+"""
+
+receipt = client.parse(raw, Receipt)
+```
+
+## 开发命令
+
+运行测试：
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 uv run --no-config --default-index https://pypi.org/simple --group dev python -m pytest -p no:cacheprovider
+```
+
+运行 Ruff：
+
+```bash
+uv run --no-config --default-index https://pypi.org/simple --group dev ruff check .
+```
+
+运行 mypy：
+
+```bash
+uv run --no-config --default-index https://pypi.org/simple --group dev mypy structured_llm
+```
+
+## 当前范围
+
+- 支持同步调用：`StructuredClient.run(...)`
+- 支持异步调用：`StructuredClient.arun(...)`
+- 支持本地解析：`StructuredClient.parse(...)`
+- 支持 Pydantic `BaseModel`、`list[...]`、`dict[...]`、`Literal`、`Enum` 等 `TypeAdapter` 可处理的类型
+- 暂不支持流式 partial object、多 provider 内置适配、BAML DSL/codegen

structured_llm-0.1.0/examples/receipt_extraction.py

@@ -0,0 +1,31 @@
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+
+from structured_llm import StructuredClient
+
+OPENAI_MODEL = "gpt-5.4-mini"
+
+
+class ReceiptItem(BaseModel):
+    name: str = Field(description="购买的商品名称")
+    quantity: int = Field(description="该商品的购买数量")
+    price: float = Field(description="该商品的单价")
+
+
+class Receipt(BaseModel):
+    merchant: str = Field(description="商户或店铺名称")
+    items: list[ReceiptItem] = Field(description="收据中的商品明细")
+    total: float = Field(description="收据最终支付总金额")
+
+
+load_dotenv()
+
+client = StructuredClient(model=OPENAI_MODEL, debug=True)
+
+receipt: Receipt = client.run(
+    prompt="提取收据信息: 咖啡店, 2杯卡布奇诺, 每杯4.50, 总计9块。",
+    schema=Receipt,
+)
+print(receipt)
+print("---")
+print(receipt.model_dump_json(indent=4))

structured_llm-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "structured-llm"
+version = "0.1.0"
+description = "Lightweight structured output runtime for Python LLM calls."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "structured-llm contributors" }]
+dependencies = [
+  "openai>=1.0.0",
+  "pydantic>=2.0.0",
+  "python-dotenv>=1.2.2",
+]
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+norecursedirs = ["sample", ".git", ".venv", ".ruff_cache"]
+asyncio_mode = "auto"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.15.20",
+]
+
+[tool.mypy]
+exclude = [
+  "^sample/"
+]

structured_llm-0.1.0/structured_llm/__init__.py

@@ -0,0 +1,22 @@
+from .client import StructuredClient
+from .errors import (
+    ProviderError,
+    StructuredLLMError,
+    StructuredParseError,
+    StructuredValidationError,
+    UnsupportedSchemaError,
+)
+from .parser import parse_structured_text
+from .schema import build_schema_spec
+
+__all__ = [
+    "ProviderError",
+    "StructuredClient",
+    "StructuredLLMError",
+    "StructuredParseError",
+    "StructuredValidationError",
+    "UnsupportedSchemaError",
+    "build_schema_spec",
+    "parse_structured_text",
+]
+