Skip to main content

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 · Getting started · Cookbook · 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:

uv add git+https://github.com/jefftriplett/django-model-agent

Or with pip:

pip install git+https://github.com/jefftriplett/django-model-agent

Once published on PyPI:

uv add django-model-agent

Or with pip:

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

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)

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:

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:

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

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:

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.

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

Metadata

Release files for django-model-agent 2026.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-model-agent 2026.1.1
File Size Uploaded Provenance Actions
django_model_agent-2026.1.1.tar.gz 54.8 kB Without provenance Details for django_model_agent-2026.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-model-agent 2026.1.1
File Interpreter ABI Platform Actions
django_model_agent-2026.1.1-py3-none-any.whl Python 3 none any Details for django_model_agent-2026.1.1-py3-none-any.whl

Total release size: 91.7 kB

Release files / django_model_agent-2026.1.1.tar.gz

Download URL django_model_agent-2026.1.1.tar.gz
Size 54.8 kB
Tags Source
SHA-256 checksum
How to use checksums
417a48f6358b7bcc9e1d0ee14b75d515746ed6d5f8fd64c9a9f7ce03b54cb1c5
BLAKE2b-256 checksum
How to use checksums
4315a7065c1ecd7164dffe3a4b84d233e021a5d43a9e5c8cd65bf553e7759dbd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Release files / django_model_agent-2026.1.1-py3-none-any.whl

Download URL django_model_agent-2026.1.1-py3-none-any.whl
Size 36.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
38f8866540e60c9c8a5fe275984c9eaacc253c5158aab5d2e3cc51045fa5f66d
BLAKE2b-256 checksum
How to use checksums
d8b2672b75d8cc387ec470dbc3d2a86b30c69d1fbab9a651bf6d0178320bd716
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Security for django-model-agent 2026.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2026.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page