django-model-agent 2026.1.1__tar.gz

django_model_agent-2026.1.1/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Django
+*.sqlite3
+db.sqlite3
+
+# Docs build output
+site/
+
+# Distribution
+*.tar.gz
+*.whl
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*

django_model_agent-2026.1.1/LICENSE.md

@@ -0,0 +1,131 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Jeff Triplett. (https://github.com/jefftriplett)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

django_model_agent-2026.1.1/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: django-model-agent
+Version: 2026.1.1
+Summary: A Django Ninja-style abstraction for binding Django models to Pydantic AI Agents
+Project-URL: Changelog, https://github.com/jefftriplett/django-model-agent/releases
+Project-URL: Documentation, https://django-model-agent.readthedocs.io/en/latest/
+Project-URL: Homepage, https://github.com/jefftriplett/django-model-agent
+Project-URL: Issues, https://github.com/jefftriplett/django-model-agent/issues
+Project-URL: Repository, https://github.com/jefftriplett/django-model-agent
+Author: Jeff Triplett
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE.md
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Requires-Python: >=3.13
+Requires-Dist: django>=5.2
+Requires-Dist: pydantic-ai>=2.22
+Requires-Dist: pydantic>=2.12
+Description-Content-Type: text/markdown
+
+# Django Model Agent
+
+> **Note:** This project is experimental and the API will change.
+
+A Django Ninja-style abstraction for binding Django models to Pydantic AI Agents.
+
+**[Documentation](https://django-model-agent.readthedocs.io/en/latest/)** · [Getting started](https://django-model-agent.readthedocs.io/en/latest/getting-started/) · [Cookbook](https://django-model-agent.readthedocs.io/en/latest/cookbook/) · [Examples](https://django-model-agent.readthedocs.io/en/latest/examples/)
+
+This library provides a declarative way to create AI agents that understand and operate on Django model instances, similar to how Django Ninja's ModelSchema provides a declarative way to serialize models.
+
+## Installation
+
+This package is not yet published on PyPI. Install directly from GitHub:
+
+```bash
+uv add git+https://github.com/jefftriplett/django-model-agent
+```
+
+Or with pip:
+
+```bash
+pip install git+https://github.com/jefftriplett/django-model-agent
+```
+
+Once published on PyPI:
+
+```bash
+uv add django-model-agent
+```
+
+Or with pip:
+
+```bash
+pip install django-model-agent
+```
+
+## Quick Start
+
+Today, the stable part of the package is the Django model/schema/tool abstraction layer. To execute prompts, subclass `ModelAgent` and implement `build_agent()` for your own `pydantic-ai` integration.
+
+### Class Attribute Style
+
+```python
+from django_model_agent import ModelAgent, ModelTool
+
+
+class RestaurantAgent(ModelAgent):
+    model = Restaurant
+    fields = ["name", "address", "hours", "neighborhood"]
+
+    _system_prompts = """
+    You are an assistant that helps reason about restaurant information.
+    Use the provided model fields as your source of truth.
+    """
+
+    tools = [UpdateHoursTool, FlagForReviewTool]
+```
+
+### Decorator Style (Pydantic-AI inspired)
+
+```python
+class RestaurantAgent(ModelAgent):
+    model = Restaurant
+    fields = ["name", "address", "hours"]
+
+    @ModelAgent.system_prompt
+    def context_prompt(self) -> str:
+        return "You help with restaurant information."
+
+    @ModelAgent.instructions
+    def dynamic_instructions(self) -> str:
+        return f"Current restaurant: {self.instance.name}"
+
+    @ModelAgent.tool
+    def get_hours(self) -> str:
+        """Get the restaurant hours."""
+        return str(self.instance.hours)
+```
+
+### Usage
+
+Inspect the schema, prompts, and tools:
+
+```python
+restaurant = Restaurant.objects.get(pk=123)
+agent = RestaurantAgent(restaurant)
+
+schema = agent.schema
+system_prompt = agent.get_system_prompts()
+instructions = agent.get_instructions()
+tools = agent.get_tools()
+
+# Override prompts at init time
+agent = RestaurantAgent(
+    restaurant,
+    system_prompt="You are a concise assistant.",
+    instructions="Focus only on hours of operation.",
+)
+```
+
+Wire in your own runtime:
+
+```python
+from pydantic_ai import Agent
+
+
+class RunnableRestaurantAgent(RestaurantAgent):
+    def build_agent(self) -> Agent:
+        return Agent(
+            model=self.schema,
+            system_prompt=self.get_system_prompts(),
+            instructions=self.get_instructions(),
+            tools=self.get_tools(),
+        )
+```
+
+## Features
+
+- **Declarative model binding**: Define which Django model fields your agent can access
+- **Field sets**: Create named groups of fields for role-based exposure
+- **Multiple prompt sources**: Combine class-level prompts with decorated methods
+- **Tool registration**: Register tools via class attributes or decorators
+- **Template support**: Use Django templates for dynamic instructions
+- **Automatic schema generation**: Pydantic schemas are generated from Django models
+
+## Init Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `instance` | The Django model instance to operate on |
+| `system_prompt` | Override or extend the class-level system prompts |
+| `instructions` | Override or extend the class-level instructions |
+| `field_set` | Name of a field set to use for schema generation |
+
+## Class Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `model` | The Django model class this agent operates on |
+| `fields` | List of field names to expose to the agent (None = all fields) |
+| `exclude` | List of field names to exclude from the schema |
+| `_system_prompts` | System prompt string or list of strings for the agent |
+| `_instructions` | Instructions string or list of strings for the agent |
+| `_instructions_template` | Path to a Django template for instructions |
+| `tools` | List of tool classes available to the agent |
+| `_field_sets` | Named groups of fields for role-based exposure |
+
+## Decorators
+
+| Decorator | Description |
+|-----------|-------------|
+| `@ModelAgent.system_prompt` | Register a method as a system prompt provider |
+| `@ModelAgent.instructions` | Register a method as an instructions provider |
+| `@ModelAgent.tool` | Register a method as a tool available to the agent |
+
+## Creating Tools
+
+```python
+from django_model_agent.tools import UpdateTool, ToolResult
+
+
+class UpdateHoursTool(UpdateTool):
+    name = "update_hours"
+    description = "Update the operating hours"
+
+    def update(self, *, new_hours: str) -> None:
+        self.instance.hours = new_hours
+        # save() is called automatically by UpdateTool
+```
+
+Or for read-only tools:
+
+```python
+from django_model_agent.tools import ReadOnlyTool
+
+
+class GetHoursTool(ReadOnlyTool):
+    name = "get_hours"
+    description = "Get the current operating hours"
+
+    def read(self, **kwargs) -> dict:
+        return {"hours": self.instance.hours}
+```
+
+## Local Development
+
+Python `3.13+` is currently required, including free-threaded (`t`) builds.
+
+```bash
+uv sync --group dev
+just test
+just lint
+```
+
+Useful commands:
+
+- `just test tests/test_model_agent.py`
+- `just lint`
+- `uv build`
+
+## License
+
+PolyForm Noncommercial License 1.0.0

django_model_agent-2026.1.1/README.md

@@ -0,0 +1,203 @@
+# Django Model Agent
+
+> **Note:** This project is experimental and the API will change.
+
+A Django Ninja-style abstraction for binding Django models to Pydantic AI Agents.
+
+**[Documentation](https://django-model-agent.readthedocs.io/en/latest/)** · [Getting started](https://django-model-agent.readthedocs.io/en/latest/getting-started/) · [Cookbook](https://django-model-agent.readthedocs.io/en/latest/cookbook/) · [Examples](https://django-model-agent.readthedocs.io/en/latest/examples/)
+
+This library provides a declarative way to create AI agents that understand and operate on Django model instances, similar to how Django Ninja's ModelSchema provides a declarative way to serialize models.
+
+## Installation
+
+This package is not yet published on PyPI. Install directly from GitHub:
+
+```bash
+uv add git+https://github.com/jefftriplett/django-model-agent
+```
+
+Or with pip:
+
+```bash
+pip install git+https://github.com/jefftriplett/django-model-agent
+```
+
+Once published on PyPI:
+
+```bash
+uv add django-model-agent
+```
+
+Or with pip:
+
+```bash
+pip install django-model-agent
+```
+
+## Quick Start
+
+Today, the stable part of the package is the Django model/schema/tool abstraction layer. To execute prompts, subclass `ModelAgent` and implement `build_agent()` for your own `pydantic-ai` integration.
+
+### Class Attribute Style
+
+```python
+from django_model_agent import ModelAgent, ModelTool
+
+
+class RestaurantAgent(ModelAgent):
+    model = Restaurant
+    fields = ["name", "address", "hours", "neighborhood"]
+
+    _system_prompts = """
+    You are an assistant that helps reason about restaurant information.
+    Use the provided model fields as your source of truth.
+    """
+
+    tools = [UpdateHoursTool, FlagForReviewTool]
+```
+
+### Decorator Style (Pydantic-AI inspired)
+
+```python
+class RestaurantAgent(ModelAgent):
+    model = Restaurant
+    fields = ["name", "address", "hours"]
+
+    @ModelAgent.system_prompt
+    def context_prompt(self) -> str:
+        return "You help with restaurant information."
+
+    @ModelAgent.instructions
+    def dynamic_instructions(self) -> str:
+        return f"Current restaurant: {self.instance.name}"
+
+    @ModelAgent.tool
+    def get_hours(self) -> str:
+        """Get the restaurant hours."""
+        return str(self.instance.hours)
+```
+
+### Usage
+
+Inspect the schema, prompts, and tools:
+
+```python
+restaurant = Restaurant.objects.get(pk=123)
+agent = RestaurantAgent(restaurant)
+
+schema = agent.schema
+system_prompt = agent.get_system_prompts()
+instructions = agent.get_instructions()
+tools = agent.get_tools()
+
+# Override prompts at init time
+agent = RestaurantAgent(
+    restaurant,
+    system_prompt="You are a concise assistant.",
+    instructions="Focus only on hours of operation.",
+)
+```
+
+Wire in your own runtime:
+
+```python
+from pydantic_ai import Agent
+
+
+class RunnableRestaurantAgent(RestaurantAgent):
+    def build_agent(self) -> Agent:
+        return Agent(
+            model=self.schema,
+            system_prompt=self.get_system_prompts(),
+            instructions=self.get_instructions(),
+            tools=self.get_tools(),
+        )
+```
+
+## Features
+
+- **Declarative model binding**: Define which Django model fields your agent can access
+- **Field sets**: Create named groups of fields for role-based exposure
+- **Multiple prompt sources**: Combine class-level prompts with decorated methods
+- **Tool registration**: Register tools via class attributes or decorators
+- **Template support**: Use Django templates for dynamic instructions
+- **Automatic schema generation**: Pydantic schemas are generated from Django models
+
+## Init Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `instance` | The Django model instance to operate on |
+| `system_prompt` | Override or extend the class-level system prompts |
+| `instructions` | Override or extend the class-level instructions |
+| `field_set` | Name of a field set to use for schema generation |
+
+## Class Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `model` | The Django model class this agent operates on |
+| `fields` | List of field names to expose to the agent (None = all fields) |
+| `exclude` | List of field names to exclude from the schema |
+| `_system_prompts` | System prompt string or list of strings for the agent |
+| `_instructions` | Instructions string or list of strings for the agent |
+| `_instructions_template` | Path to a Django template for instructions |
+| `tools` | List of tool classes available to the agent |
+| `_field_sets` | Named groups of fields for role-based exposure |
+
+## Decorators
+
+| Decorator | Description |
+|-----------|-------------|
+| `@ModelAgent.system_prompt` | Register a method as a system prompt provider |
+| `@ModelAgent.instructions` | Register a method as an instructions provider |
+| `@ModelAgent.tool` | Register a method as a tool available to the agent |
+
+## Creating Tools
+
+```python
+from django_model_agent.tools import UpdateTool, ToolResult
+
+
+class UpdateHoursTool(UpdateTool):
+    name = "update_hours"
+    description = "Update the operating hours"
+
+    def update(self, *, new_hours: str) -> None:
+        self.instance.hours = new_hours
+        # save() is called automatically by UpdateTool
+```
+
+Or for read-only tools:
+
+```python
+from django_model_agent.tools import ReadOnlyTool
+
+
+class GetHoursTool(ReadOnlyTool):
+    name = "get_hours"
+    description = "Get the current operating hours"
+
+    def read(self, **kwargs) -> dict:
+        return {"hours": self.instance.hours}
+```
+
+## Local Development
+
+Python `3.13+` is currently required, including free-threaded (`t`) builds.
+
+```bash
+uv sync --group dev
+just test
+just lint
+```
+
+Useful commands:
+
+- `just test tests/test_model_agent.py`
+- `just lint`
+- `uv build`
+
+## License
+
+PolyForm Noncommercial License 1.0.0

django_model_agent-2026.1.1/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+  "pytest-django>=4.5",
+  "zensical>=0.0.52"
+]
+
+[project]
+authors = [
+  { name = "Jeff Triplett" }
+]
+classifiers = [
+  "Framework :: Django",
+  "Framework :: Django :: 5.2",
+  "Framework :: Django :: 6.0",
+  "Framework :: Django :: 6.1",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Free Threading :: 3 - Stable"
+]
+dependencies = [
+  "django>=5.2",
+  "pydantic>=2.12",
+  "pydantic-ai>=2.22"
+]
+description = "A Django Ninja-style abstraction for binding Django models to Pydantic AI Agents"
+license = "PolyForm-Noncommercial-1.0.0"
+name = "django-model-agent"
+readme = "README.md"
+requires-python = ">=3.13"
+version = "2026.1.1"
+
+[project.urls]
+Changelog = "https://github.com/jefftriplett/django-model-agent/releases"
+Documentation = "https://django-model-agent.readthedocs.io/en/latest/"
+Homepage = "https://github.com/jefftriplett/django-model-agent"
+Issues = "https://github.com/jefftriplett/django-model-agent/issues"
+Repository = "https://github.com/jefftriplett/django-model-agent"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/README.md",
+  "/src",
+  "/tests"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/django_model_agent"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+addopts = "-v --tb=short"
+python_files = ["test_*.py"]
+pythonpath = [".", "src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+extend-exclude = ["src/django_model_agent/migrations"]
+
+[tool.ruff.lint]
+# Declarative class attributes (`fields = [...]`, `tools = [...]`) are this
+# library's API, so mutable class defaults are intended.
+ignore = ["RUF012"]