Metadata-Version: 2.4
Name: drf-llm-gateway
Version: 1.0.0
Summary: Expose Django REST Framework serializers and viewsets as OpenAI / MCP tools with automatic JSON Schema generation
Project-URL: Homepage, https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/
Project-URL: Documentation, https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/getting-started/
Project-URL: Repository, https://github.com/MahmoudGShake/MahmoudPackages/tree/master/drf-llm-gateway
Project-URL: Issues, https://github.com/MahmoudGShake/MahmoudPackages/issues
Project-URL: Changelog, https://github.com/MahmoudGShake/MahmoudPackages/blob/master/drf-llm-gateway/CONTRIBUTING.md
Author-email: Mahmoud Gamal <mahmoudgshaker2018@gmail.com>
Maintainer-email: Mahmoud Gamal <mahmoudgshaker2018@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-tools,django,djangorestframework,drf,function-calling,json-schema,llm,mcp,model-context-protocol,openai
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: django<5.3,>=4.2
Requires-Dist: djangorestframework>=3.14
Provides-Extra: dev
Requires-Dist: black>=24.10.0; extra == 'dev'
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: django-stubs[compatible-mypy]>=5.1.0; extra == 'dev'
Requires-Dist: djangorestframework-stubs[compatible-mypy]>=3.15.0; extra == 'dev'
Requires-Dist: hypothesis>=6.112.0; extra == 'dev'
Requires-Dist: jsonschema>=4.23.0; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5.0; extra == 'dev'
Requires-Dist: mkdocs>=1.6.0; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.26.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=3.8.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-django>=4.9.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.6.9; extra == 'dev'
Requires-Dist: tox-gh-actions>=3.2.0; extra == 'dev'
Requires-Dist: tox>=4.21.0; extra == 'dev'
Requires-Dist: twine>=5.1.0; extra == 'dev'
Requires-Dist: types-jsonschema; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: hypothesis>=6.112.0; extra == 'test'
Requires-Dist: jsonschema>=4.23.0; extra == 'test'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest-django>=4.9.0; extra == 'test'
Requires-Dist: pytest>=8.3.0; extra == 'test'
Description-Content-Type: text/markdown

# drf-llm-gateway

[![PyPI version](https://img.shields.io/pypi/v/drf-llm-gateway.svg)](https://pypi.org/project/drf-llm-gateway/)
[![Python versions](https://img.shields.io/pypi/pyversions/drf-llm-gateway.svg)](https://pypi.org/project/drf-llm-gateway/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Turn your existing Django REST Framework viewsets into tools an LLM can
call — OpenAI function-calling format, MCP (Model Context Protocol) tool
format, or plain JSON Schema — generated automatically from the
serializers you already have.

```python
from rest_framework import viewsets
from drf_llm_gateway import expose_as_tool


@expose_as_tool(actions=["list", "retrieve", "create"])
class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
```

```python
from drf_llm_gateway import default_registry
from drf_llm_gateway.openai_tools import to_openai_tools

tools = to_openai_tools(default_registry)
# [{"type": "function", "function": {"name": "article_list", "description": "...",
#   "parameters": {"type": "object", "properties": {...}}}}, ...]
```

## Why

Wiring an LLM agent up to call your existing API usually means hand-writing
and hand-maintaining a parallel set of tool/function schemas — which drift
out of sync with your serializers the moment either side changes. This
package derives the schema *from the serializer itself* at generation
time, so there is nothing to keep in sync: change a field on the
serializer, regenerate the tools, done.

## Features

- **Automatic JSON Schema generation** from any DRF serializer — every
  standard field type, nested serializers, list serializers, related
  fields, choice fields, and more.
- **OpenAI function-calling format** and **MCP tool format** exporters.
- **Tool registry** — a decorator (`@expose_as_tool`) that registers a
  viewset's actions as callable tools without any schema duplication.
- **Runtime executor** — validates arguments against the real serializer
  and dispatches to the real viewset action, respecting DRF permission and
  authentication classes.
- **Auth/permission metadata** attached to every tool definition, so a
  gateway can decide what an agent identity may call before it calls it.
- **Schema versioning** — every generated tool carries a content hash that
  changes whenever its schema changes, so consumers can detect drift.
- **CLI** (`generate_llm_tools` management command) to export the full
  tool set as JSON for any external agent framework.
- Fully typed, PEP 561 compatible, `mypy --strict` clean.

## Installation

```bash
pip install drf-llm-gateway
```

Requires Python 3.10+, Django 4.2+, and Django REST Framework 3.14+.

## Quick Start

See [`docs/quickstart.md`](docs/quickstart.md) for a complete walkthrough,
including calling a tool end-to-end from a validated argument dict.

## Documentation

Full documentation: <https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway>

- [Getting Started](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/getting-started)
- [Installation](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/installation)
- [Configuration](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/configuration) / [Settings](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/settings)
- [Quick Start](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/quickstart)
- [Advanced Usage](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/advanced-usage)
- [Architecture](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/architecture)
- [API Reference](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/api-reference)
- [Examples](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/examples)
- [Common Patterns](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/common-patterns)
- [Performance](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/performance)
- [Security](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/security)
- [Testing](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/testing)
- [Deployment](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/deployment)
- [FAQ](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/faq)
- [Troubleshooting](https://mahmoudgshake.github.io/MahmoudPackages/drf-llm-gateway/troubleshooting)

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](https://github.com/MahmoudGShake/MahmoudPackages/blob/master/drf-llm-gateway/CONTRIBUTING.md).

## License

MIT — see [LICENSE](https://github.com/MahmoudGShake/MahmoudPackages/blob/master/drf-llm-gateway/LICENSE).
