Django ORM

Models of the MCPServer app: the search index of The Smarter Project’s repositories, and the audit trail of the operations tools.

RepositoryIndex records, for each repository of SMARTER_PROJECT_REPOSITORIES, the commit that is indexed, and RepositoryFile holds the text of each of its files. The index is built by smarter.apps.mcpserver.services.indexing.github.index_repository(), and replaced whenever the repository’s branch moves to a new commit.

OperationsToolCall records every call to a staff-only tool of the MCPServer (smarter.apps.mcpserver.protocol.staff): who called it, for which help desk ticket, with which arguments, and whether it failed. The tools read logs and users’ data, so each call is kept until a superuser deletes it.

Note

Experimental. The MCPServer was designed and coded by Claude Code (Anthropic’s Claude Opus 5.5), with Lawrence McDaniel as co-author. It is experimental, and will be documented.

class smarter.apps.mcpserver.models.OperationsToolCall(*args, **kwargs)[source]

Bases: TimestampedModel

One call to a staff-only tool of the MCPServer, for the audit trail.

The operations tools read logs and users’ data, so the server writes a row for every call, whether it succeeded or not: who called it, for which help desk ticket, with which arguments, and how long its result was. The rows are read-only in the Django admin (OperationsToolCallAdmin), and are kept until a superuser deletes them.

Parameters:

  • id (Unknown) – Primary key: ID

  • created_at (Unknown) – Created at

  • updated_at (Unknown) – Updated at

  • username (Unknown) –

    Username. The user’s username at the time of the call, which outlives the user.

    The user’s username at the time of the call, which outlives the user.

  • tool (Unknown) –

    Tool. The tool, e.g. search_logs.

    The tool’s name, e.g. search_logs.

  • ticket (Unknown) –

    Ticket. The help desk ticket, or reason, that the caller gave.

    The help desk ticket, or reason, that the caller gave for the call. Every operations tool requires one. Indexed, to find every call made for a ticket.

  • arguments (Unknown) –

    Arguments. The tool call’s other arguments.

    The tool call’s other arguments, without the ticket.

  • is_error (Unknown) –

    Is error. Whether the tool returned an error.

    Whether the tool returned an error instead of a result.

  • characters (Unknown) –

    Characters. The length of the result.

    The length of the tool’s result, in characters.

Relationship fields:

Parameters:

user (Unknown) –

User. The staff user whose api key called the tool. Empty once the user is deleted: see username. (related name: +)

The staff user whose api key called the tool. Set to None when the user is deleted, so that the row outlives them: see username.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

exception NotUpdated

Bases: ObjectNotUpdated, DatabaseError

arguments

JSONField

Arguments. The tool call’s other arguments.

The tool call’s other arguments, without the ticket.

Type:

Type

characters

PositiveIntegerField

Characters. The length of the result.

The length of the tool’s result, in characters.

Type:

Type

created_at

DateTimeField

Created at

Timestamp indicating when the model instance was created.

This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.

Type:

Type

id: int

BigAutoField

Primary key: ID

The row’s primary key, which Django adds to every concrete model. Declared, without a value, only so that type checkers know it: Django ignores a bare annotation.

Type:

Type

is_error

BooleanField

Is error. Whether the tool returned an error.

Whether the tool returned an error instead of a result.

Type:

Type

objects = <django.db.models.Manager object>
ticket

CharField

Ticket. The help desk ticket, or reason, that the caller gave.

The help desk ticket, or reason, that the caller gave for the call. Every operations tool requires one. Indexed, to find every call made for a ticket.

Type:

Type

tool

CharField

Tool. The tool, e.g. search_logs.

The tool’s name, e.g. search_logs.

Type:

Type

updated_at

DateTimeField

Updated at

Timestamp indicating when the model instance was last updated.

This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.

Type:

Type

user

ForeignKey to User

User. The staff user whose api key called the tool. Empty once the user is deleted: see username. (related name: +)

The staff user whose api key called the tool. Set to None when the user is deleted, so that the row outlives them: see username.

Type:

Type

user_id

Internal field, use user instead.

username

CharField

Username. The user’s username at the time of the call, which outlives the user.

The user’s username at the time of the call, which outlives the user.

Type:

Type

class smarter.apps.mcpserver.models.RepositoryFile(*args, **kwargs)[source]

Bases: TimestampedModel

One text file of an indexed repository, or one post of the blog.

The indexers replace every file of an index when its repository moves to a new commit. The MCP server’s tools search their content, and read it back by path. A file is unique in its index by its path.

Parameters:

  • id (Unknown) – Primary key: ID

  • created_at (Unknown) – Created at

  • updated_at (Unknown) – Updated at

  • path (Unknown) –

    Path. The file’s path in the repository.

    The file’s path in the repository, e.g. docs/source/index.rst, or a post’s permalink path.

  • kind (Unknown) –

    Kind

    Whether the file is documentation or code: see RepositoryFileKind.

  • title (Unknown) –

    Title. A document’s first heading.

    A document’s first heading, or a post’s title. Empty for code.

  • content (Unknown) –

    Content

    The file’s text, which the tools search and read.

  • size (Unknown) –

    Size. Bytes.

    The file’s size, in bytes.

  • line_count (Unknown) –

    Line count

    How many lines the file has, counted when it was indexed.

Relationship fields:

Parameters:

index (Unknown) –

Index (related name: files)

The index that the file belongs to. Its files are deleted with it.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

exception NotUpdated

Bases: ObjectNotUpdated, DatabaseError

content

TextField

Content

The file’s text, which the tools search and read.

Type:

Type

created_at

DateTimeField

Created at

Timestamp indicating when the model instance was created.

This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.

Type:

Type

get_kind_display(*, field=<django.db.models.CharField: kind>)

Shows the label of the kind. See get_FOO_display() for more information.

id: int

BigAutoField

Primary key: ID

The row’s primary key, which Django adds to every concrete model. Declared, without a value, only so that type checkers know it: Django ignores a bare annotation.

Type:

Type

index

ForeignKey to RepositoryIndex

Index (related name: files)

The index that the file belongs to. Its files are deleted with it.

Type:

Type

index_id

Internal field, use index instead.

kind

CharField

Kind

Choices:

  • documentation

  • code

Whether the file is documentation or code: see RepositoryFileKind.

Type:

Type

line_count

PositiveIntegerField

Line count

How many lines the file has, counted when it was indexed.

Type:

Type

objects = <django.db.models.Manager object>
path

CharField

Path. The file’s path in the repository.

The file’s path in the repository, e.g. docs/source/index.rst, or a post’s permalink path.

Type:

Type

size

PositiveIntegerField

Size. Bytes.

The file’s size, in bytes.

Type:

Type

title

CharField

Title. A document’s first heading.

A document’s first heading, or a post’s title. Empty for code.

Type:

Type

updated_at

DateTimeField

Updated at

Timestamp indicating when the model instance was last updated.

This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.

Type:

Type

class smarter.apps.mcpserver.models.RepositoryFileKind(*values)[source]

Bases: TextChoices

What a file of a repository is, in RepositoryFile.kind.

The search tools use it to search only the documentation, or only the code.

CODE = 'code'

Source code and configuration.

DOCUMENTATION = 'documentation'

Prose, e.g. reStructuredText and Markdown.

class smarter.apps.mcpserver.models.RepositoryIndex(*args, **kwargs)[source]

Bases: TimestampedModel

The index of one of The Smarter Project’s repositories, or of its blog.

There is one row per repository of SMARTER_PROJECT_REPOSITORIES, plus one for the blog, whose repository is the blog’s name, e.g. blog.smarter.sh. The row records which commit is indexed, and whether the last attempt to index it failed. The text of the indexed files is in its RepositoryFile rows, index.files.

It is written only by the indexers, smarter.apps.mcpserver.services.indexing.github.index_repository() and smarter.apps.mcpserver.services.indexing.blog.index_blog().

Parameters:

  • id (Unknown) – Primary key: ID

  • created_at (Unknown) – Created at

  • updated_at (Unknown) – Updated at

  • repository (Unknown) –

    Repository. The repository’s name, e.g. smarter-cli.

    The repository’s name, e.g. smarter-cli, or the blog’s, e.g. blog.smarter.sh. Unique.

  • commit_sha (Unknown) –

    Commit sha. The indexed commit.

    The SHA of the commit whose files are indexed, or None if nothing is indexed yet. The blog, which has no commits, stores a fingerprint of its posts here.

  • status (Unknown) –

    Status

    Whether the repository has an index to search: see RepositoryIndexStatus.

  • indexed_at (Unknown) –

    Indexed at. When the indexed commit was indexed.

    When the indexed commit was indexed, or None if nothing is indexed yet.

  • file_count (Unknown) –

    File count

    How many files of the indexed commit are stored, as RepositoryFile rows.

  • total_bytes (Unknown) –

    Total bytes

    The total size, in bytes, of the stored files.

  • error (Unknown) –

    Error. Why the last attempt to index the repository failed.

    Why the last attempt to index the repository failed, or None if it succeeded. A ready index with an error is still searched, at its previous commit.

Reverse relationships:

Parameters:

files (Unknown) – All files of this repository index (related name of index)

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

exception NotUpdated

Bases: ObjectNotUpdated, DatabaseError

commit_sha

CharField

Commit sha. The indexed commit.

The SHA of the commit whose files are indexed, or None if nothing is indexed yet. The blog, which has no commits, stores a fingerprint of its posts here.

Type:

Type

created_at

DateTimeField

Created at

Timestamp indicating when the model instance was created.

This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.

Type:

Type

error

TextField

Error. Why the last attempt to index the repository failed.

Why the last attempt to index the repository failed, or None if it succeeded. A ready index with an error is still searched, at its previous commit.

Type:

Type

file_count

PositiveIntegerField

File count

How many files of the indexed commit are stored, as RepositoryFile rows.

Type:

Type

files

Reverse ForeignKey from RepositoryFile

All files of this repository index (related name of index)

Type:

Type

get_status_display(*, field=<django.db.models.CharField: status>)

Shows the label of the status. See get_FOO_display() for more information.

id: int

BigAutoField

Primary key: ID

The row’s primary key, which Django adds to every concrete model. Declared, without a value, only so that type checkers know it: Django ignores a bare annotation.

Type:

Type

indexed_at

DateTimeField

Indexed at. When the indexed commit was indexed.

When the indexed commit was indexed, or None if nothing is indexed yet.

Type:

Type

property is_ready: bool

Whether the repository has an index to search.

Returns:

True if status is ready, even if the last refresh failed.

objects = <django.db.models.Manager object>
repository

CharField

Repository. The repository’s name, e.g. smarter-cli.

The repository’s name, e.g. smarter-cli, or the blog’s, e.g. blog.smarter.sh. Unique.

Type:

Type

status

CharField

Status

Choices:

  • pending

  • ready

  • failed

Whether the repository has an index to search: see RepositoryIndexStatus.

Type:

Type

total_bytes

PositiveBigIntegerField

Total bytes

The total size, in bytes, of the stored files.

Type:

Type

updated_at

DateTimeField

Updated at

Timestamp indicating when the model instance was last updated.

This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.

Type:

Type

class smarter.apps.mcpserver.models.RepositoryIndexStatus(*values)[source]

Bases: TextChoices

The status of a repository’s index, in RepositoryIndex.status.

A repository starts pending. It becomes ready once it is indexed, and stays ready when a later refresh fails, so that its last good index is still searched. It is failed only when it has never been indexed.

FAILED = 'failed'

The repository could not be indexed, and has no index.

PENDING = 'pending'

The repository has not been indexed yet.

READY = 'ready'

The repository is indexed.

The last attempt to refresh it may have failed: see error.