toolschema 1.0.0__tar.gz

toolschema-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Discussions & questions
+    url: https://github.com/false200/toolschema/issues
+    about: Open an issue with a clear title and description.

toolschema-1.0.0/.github/ISSUE_TEMPLATE/issue.yml

@@ -0,0 +1,32 @@
+name: Issue
+description: Report a bug or request a feature
+title: "[Issue]: "
+labels: []
+body:
+  - type: input
+    id: title_summary
+    attributes:
+      label: Title
+      description: Short summary of the issue (also edit the issue title above).
+      placeholder: "MCP adapter leaves $ref in inputSchema"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened, what you expected, and steps to reproduce (if applicable).
+      placeholder: |
+        ## What happened
+
+        ## What you expected
+
+        ## Steps to reproduce
+
+        ## Environment
+        - Python version:
+        - toolschema version:
+        - Integration (FastMCP / LangChain / etc.):
+    validations:
+      required: true

toolschema-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,7 @@
+## Title
+
+<!-- Short summary of the change (also edit the PR title above) -->
+
+## Description
+
+<!-- What changed, why, and how you tested it -->

toolschema-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff check
+        run: uv run ruff check src tests
+
+      - name: Pytest
+        run: uv run pytest -v
+
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies with integration extras
+        run: uv sync --extra dev --extra fastmcp --extra langchain --extra openai-agents --extra pydantic-ai
+
+      - name: Ruff check
+        run: uv run ruff check src tests
+
+      - name: Integration, MCP smoke, parity, and deep agent tests
+        run: uv run pytest -v tests/test_integrations.py tests/test_parity.py tests/test_mcp_smoke.py tests/test_init.py tests/test_deep_agents.py
+
+      - name: Example smoke checks
+        run: |
+          uv run python examples/02_mcp_server.py --check
+          uv run python examples/03_langchain.py
+          uv run python examples/deep_agents_demo.py
+
+      - name: Init scaffold smoke
+        run: |
+          uv run toolschema init ci-smoke-test --path /tmp
+          cd /tmp/ci-smoke-test
+          uv add --editable "${{ github.workspace }}[fastmcp]"
+          uv sync
+          uv run python -m ci_smoke_test --check

toolschema-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.eggs/
+*.egg
+.mypy_cache/
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

toolschema-1.0.0/AGENTS.md

@@ -0,0 +1,165 @@
+# AGENTS.md — Instructions for AI coding agents
+
+This file tells automated agents (Cursor, Claude Code, Copilot, etc.) **how to implement `toolschema`** without breaking design intent.
+
+## Mission
+
+Build **Layer 1 only**: `(Python function + type hints) → canonical JSON Schema → provider-specific adapters`.
+
+Do **not** build agent orchestration, MCP transport, or replace Pydantic validation.
+
+## Read first
+
+1. [README.md](./README.md) — full problem, architecture, build plan
+2. [Pre-PEP thread](https://discuss.python.org/t/pre-pep-discussion-typing-tool-inspect-tool-schema-close-the-zod-gap-for-python-agent-dev/107431) — target API shape
+
+## Hard rules
+
+| Rule | Reason |
+|------|--------|
+| Core package MUST NOT import FastMCP, LangChain, OpenAI SDK | Zero framework lock-in |
+| All provider output goes through `ToolDefinition` IR | Single source of truth |
+| JSON Schema 2020-12 is canonical internal dialect | Pre-PEP alignment |
+| MCP adapter defaults `inline_refs=True` | Claude Desktop / Copilot break on `$ref` |
+| Every type mapping needs a unit test | Schema bugs break agents silently |
+| Golden snapshot tests for each adapter | Prevent regressions |
+| Match Pre-PEP API: `schema(fn)`, `@tool` | Future stdlib migration |
+
+## Implementation order
+
+```
+Phase 0: pyproject.toml, CI, empty package
+Phase 1: _introspect.py, _types.py, _ir.py, @tool, schema()
+Phase 2: adapters/openai.py, adapters/mcp.py
+Phase 3: cli.py inspect command
+Phase 4: integrations/* (optional extras)
+Phase 5: PyPI, examples, docs
+```
+
+**Do not start Phase 4 before Phase 1–2 tests pass.**
+
+## Key types
+
+```python
+# src/toolschema/_ir.py
+@dataclass(frozen=True)
+class ToolDefinition:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    output: dict[str, Any] | None = None
+
+    def to_json_schema(self) -> dict: ...
+    def to_openai(self, *, strict: bool = False) -> dict: ...
+    def to_mcp(self, *, inline_refs: bool = True) -> dict: ...
+    def to_anthropic(self) -> dict: ...
+    def to_gemini(self) -> dict: ...
+```
+
+## Type → JSON Schema mapping (Phase 1)
+
+| Python | JSON Schema |
+|--------|-------------|
+| `str` | `{"type": "string"}` |
+| `int` | `{"type": "integer"}` |
+| `float` | `{"type": "number"}` |
+| `bool` | `{"type": "boolean"}` |
+| `T \| None` | `{"anyOf": [schema(T), {"type": "null"}]}` |
+| `list[T]` | `{"type": "array", "items": schema(T)}` |
+| `dict[str, T]` | `{"type": "object", "additionalProperties": schema(T)}` |
+| `Literal["a"]` | `{"enum": ["a"]}` |
+| default value | `"default"` key; omit from `"required"` |
+
+## Annotated / Field
+
+```python
+Annotated[str, Field(description="...", min_length=1)]
+# → {"type": "string", "description": "...", "minLength": 1}
+```
+
+Support plain string in Annotated as shorthand (Pre-PEP + Claude SDK pattern):
+
+```python
+Annotated[str, "City name"]  # → description only
+```
+
+## OpenAI strict adapter
+
+When `strict=True`:
+
+- Set `"additionalProperties": false` on parameters object
+- Every property key must appear in `"required"`
+
+## MCP adapter
+
+Output shape:
+
+```json
+{
+  "name": "...",
+  "description": "...",
+  "inputSchema": { "type": "object", ... },
+  "outputSchema": { ... }
+}
+```
+
+Run `$ref` inlining before return if `inline_refs=True`.
+
+## Test fixtures
+
+Create `tests/fixtures.py`:
+
+```python
+def add(a: int, b: int = 1) -> int:
+    """Add two numbers."""
+    return a + b
+
+def search_github(repo: str, query: str, limit: int = 10) -> list[dict]:
+    """Search issues in a GitHub repository."""
+    ...
+```
+
+Use these in all snapshot tests.
+
+## Commands
+
+```bash
+uv sync
+uv run pytest -v
+uv run ruff check src tests
+uv run ruff format src tests
+```
+
+## What NOT to do
+
+- ❌ Add LangChain import to `src/toolschema/_types.py`
+- ❌ Generate schema separately in each adapter (use IR only)
+- ❌ Full Pydantic validation in core (thin `validate()` optional in Phase 2+)
+- ❌ Support every Python type in MVP (defer ParamSpec, generics)
+- ❌ Change golden snapshots without explaining in PR
+
+## Success definition
+
+An agent can run:
+
+```python
+from toolschema import tool, schema
+
+@tool
+def greet(name: str) -> str:
+    """Say hello."""
+    return f"Hello, {name}"
+
+assert schema(greet).to_mcp()["name"] == "greet"
+assert "name" in schema(greet).to_openai()["function"]["parameters"]["properties"]
+```
+
+And:
+
+```bash
+uv run pytest  # all green
+```
+
+## Questions?
+
+Open a GitHub issue with label `design` before large architectural changes.

toolschema-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy toward other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers via [GitHub Issues](https://github.com/false200/toolschema/issues). All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

toolschema-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to toolschema
+
+Thanks for helping improve toolschema. PRs and issues are welcome.
+
+## Before you start
+
+1. Read [README.md](README.md) for scope and API overview.
+2. Read [AGENTS.md](AGENTS.md) if you use an AI coding agent — it defines hard design rules.
+3. Search [existing issues](https://github.com/false200/toolschema/issues) to avoid duplicate work.
+
+## Development setup
+
+```sh
+git clone https://github.com/false200/toolschema.git
+cd toolschema
+uv sync --extra dev --extra fastmcp --extra langchain --extra openai-agents --extra pydantic-ai
+```
+
+## Making changes
+
+1. Fork the repo and create a branch from `main`.
+2. Make focused changes — one feature or fix per PR.
+3. Add or update tests for behavior you change.
+4. Run checks before opening a PR:
+
+```sh
+uv run pytest -v
+uv run ruff check src tests
+uv run ruff format src tests
+```
+
+5. If adapter output changes intentionally, update golden snapshots in `tests/snapshots/` and explain why in the PR.
+
+## Design rules (summary)
+
+- **Layer 1 only** — schema generation, not agent orchestration.
+- **No framework imports in core** — FastMCP, LangChain, OpenAI SDK belong in `integrations/` only.
+- **Single IR** — all adapters read from `ToolDefinition`; never regenerate schema in an adapter.
+- **MCP defaults** — `inline_refs=True` for Claude Desktop / Copilot compatibility.
+
+## Pull requests
+
+Use the [pull request template](.github/pull_request_template.md). Keep PRs small and describe:
+
+- What changed
+- Why it changed
+- How you tested it
+
+## Issues
+
+Use the [issue template](.github/ISSUE_TEMPLATE/issue.yml). A clear title and short description is enough to get started.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

toolschema-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 toolschema contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.