Skip to main content

django-llms-manager

Checks License

Manage llms.txt and llms-full.txt content for AI assistants through the Django admin. Edit Markdown or import a UTF-8 file, save revisions, review changes, and publish a selected version at the site root or in a nested directory.

Requires Python 3.10+ and Django 4.2+. Supported Python/Django combinations follow Django's compatibility table.

CI is configured to check all 22 officially supported combinations of the declared Python and Django series, using the latest available patch release of each Django series:

Python Django series
3.10 4.2, 5.0, 5.1, 5.2
3.11 4.2, 5.0, 5.1, 5.2
3.12 4.2, 5.0, 5.1, 5.2, 6.0, 6.1
3.13 5.1, 5.2, 6.0, 6.1
3.14 5.2, 6.0, 6.1
3.15 6.1

Setup

To use a local checkout in an existing Django project managed with uv, add it as a path dependency:

uv add /path/to/django-llms-manager

Add the application to a Django project with the admin enabled:

INSTALLED_APPS = [
    ...,
    "llms_manager",
]

Mount the publication routes at the site root, after specific application routes and before any catch-all route:

from django.urls import include, path

urlpatterns = [
    ...,
    path("", include("llms_manager.urls")),
]

Apply the included migrations using the host project's settings:

uv run python manage.py migrate

Open llms in the Django admin to create named documents. Each document has its own editor and revision history. Open Publications to configure their public addresses and select the revisions served there.

Revisions and publishing

  1. Create or select a document and open its Editor or Revision history.
  2. Edit the complete Markdown document, or use Load file into editor to import a UTF-8 file. Importing replaces the editor contents without saving a revision.
  3. Save revision creates an immutable file snapshot belonging to that document. Revisions are numbered from 1 independently within each document.
  4. Create or open a Publication. Its address consists of a directory and a file name selected from llms.txt and llms-full.txt.
  5. In the publication card, select a document and click Show revisions. Select any of its saved revisions and click Review revision. Selection and review are available before saving a new publication; the entered address is preserved.
  6. Review the content and diff against the revision currently published at this particular address. If the address is new or has changed, click Save address; the selected document and revision are kept. Then click Publish revision. Both buttons are at the top of the card. Publishing becomes available after reviewing a revision and saving the address. Save address only saves the address; changing the selection or reviewing a diff does not publish anything.

When the selected revision is already published at this address, the card shows its status, complete content, and public link. The diff is hidden.

Directory File name Public address
/ llms.txt /llms.txt
/ llms-full.txt /llms-full.txt
/courses/python/ llms.txt /courses/python/llms.txt
/courses/python/ llms-full.txt /courses/python/llms-full.txt

Each directory/file-name pair is unique. Directory input is normalized: for example, courses/python becomes /courses/python/. Editing a saved directory or file name changes the public URL while keeping its selected revision.

Publication changes are independent for each address. If its selected revision has changed since the review, publication is rejected and the updated diff is shown. Updating another address does not invalidate the review.

The revision history records the author and creation date. Use Edit as new revision to continue working from a saved snapshot. To restore an older version, select it in the publication card, review its diff, and publish it again. Any saved revision can be selected, including an older revision of a different document. Publication actions are recorded in the publication's Django admin History.

Public files are available without logging in and return the selected content as text/plain; charset=utf-8. The publication view accepts GET and HEAD and only reads existing publications; requesting a URL does not create documents, revisions, or publications. A configured address without a selected revision returns an empty response with status 200. An unconfigured address returns 404. The routes match only the two supported file names, at the root or in nested directories. Markdown is displayed as text; the application does not enforce a section schema. Links between root and nested files belong to the Markdown content. The library does not automatically assemble llms-full.txt from other publications.

The view_document permission allows viewing document history and previews. The add_document permission allows creating documents. The change_document permission allows renaming documents and importing and saving revisions.

The view_publication permission allows viewing publication cards and history. The add_publication permission allows configuring new addresses, and change_publication allows changing addresses and confirming publications. Selecting and publishing document revisions also requires view_document or change_document. Removing an address through the standard delete_publication permission does not delete its document or revision files. Documents and revisions cannot be deleted through the library's admin interface.

Each Publication points to one selected revision; its document is determined through Revision.document. The same revision can be served at multiple addresses. Changing a publication preserves all documents, their revisions, and their files. Address uniqueness uses a normal constraint on directory and file name, without conditional indexes.

File storage

Revision files use Django's default storage, selected by STORAGES["default"]. The database stores file names and revision metadata. Each snapshot has a unique key such as llms_manager/<uuid>.txt.

Public addresses and storage keys are independent. For example, /courses/python/llms-full.txt serves the file referenced by that publication's revision. The directory and public file name do not determine the storage key. Each revision gets a new key, so saving another revision preserves earlier files.

For local storage, configure MEDIA_ROOT, for example:

MEDIA_ROOT = BASE_DIR / "media"

For S3, install django-storages[s3] in the host project and configure its S3 backend, for example:

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.s3.S3Storage",
        "OPTIONS": {"bucket_name": "my-bucket"},
    },
    "staticfiles": {
        "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
    },
}

Credentials and other backend options belong to the host project's configuration. The library reads files through the Storage API and serves their content at the configured public endpoint. Other file fields using the default storage share this backend. Access to storage objects themselves follows the project's storage configuration.

Database and file storage are separate systems. Keep both when backing up or moving the application. When changing storage backends, copy existing revision files while preserving the keys stored in the database. A database rollback in an enclosing transaction can leave an unreferenced file in storage.

Caching

Public file content uses Django's default cache from CACHES. Set the lifetime in the host project's settings:

LLMS_MANAGER_CACHE_TIMEOUT = 60  # Seconds; 0 or None disables caching.

If the setting is absent, the default is 60 seconds. Set 0 or None to disable caching. Positive values must be integers. Invalid values, including strings, booleans, floats, and negative integers, disable caching and emit a RuntimeWarning when a published revision is requested. Repeated warnings follow the project's Python warning filters.

Each request looks up the publication in the database to determine its current revision. The revision's text is read from the cache, or loaded from Storage and cached on a miss. Publishing another revision selects a different cache key, so the next request serves the newly selected content. Restoring an earlier revision can reuse its cached text until that entry expires. The same revision can share its cached text across multiple public addresses.

This caches revision text on the server; it does not add HTTP cache headers. Address changes and deletions take effect on the next request. Admin previews continue to read files directly from Storage.

Development

Development uses Python 3.13 and uv. Run these commands from the repository root to prepare the environment:

uv sync
uv run pre-commit install

The .python-version file selects Python 3.13 for development; package support starts at Python 3.10 as declared in pyproject.toml. uv sync synchronizes .venv/ with the project dependencies and uv.lock. The dev dependency group includes the test group with pytest and pytest-django. Pytest uses tests.settings.

tests/ contains a minimal Django project with the admin enabled and a SQLite database stored in db.sqlite3. It is not part of the distributed package.

To run the project locally:

export DJANGO_SETTINGS_MODULE=tests.settings
uv run python -m django migrate
uv run python -m django createsuperuser
uv run python -m django runserver

Open the admin or llms.txt. Before a root publication is created, /llms.txt returns 404. After saving its address, it returns an empty file until a revision is published. Local revision files are stored in media/llms_manager/. The development project defaults to Russian (LANGUAGE_CODE = "ru" in tests/settings.py); set it to "en" for English.

Run the checks from the repository root:

uv run ruff check .
uv run ruff format --check .
uv run python -m django check --settings=tests.settings
uv run python -m django makemigrations llms_manager --check --dry-run --settings=tests.settings
uv run pytest

After model changes, generate and review migrations with uv run python -m django makemigrations llms_manager --settings=tests.settings. Then apply them with uv run python -m django migrate --settings=tests.settings. The initial setup uses the included migrations.

Ruff handles linting, import sorting, and formatting through pre-commit and targets Python 3.10 syntax. To run all hooks, including automatic fixes and formatting:

uv run pre-commit run --all-files

Pre-commit checks files tracked by Git. The direct Ruff commands above also cover new Python files before they are tracked.

CI builds the distributions, checks their metadata, installs the wheel with each Python/Django pair in the matrix, checks for missing migrations, and runs the tests from outside the source directory.

Translations

English (en) and Russian (ru) catalogs are stored in llms_manager/locale/. The interface uses the active Django language. To use Russian by default, set LANGUAGE_CODE = "ru" in the host project with USE_I18N = True.

To update the catalogs, run these commands with GNU gettext installed:

cd llms_manager
uv run python -m django makemessages -l en -l ru

Edit msgstr values in locale/*/LC_MESSAGES/django.po. Review entries marked fuzzy and remove that flag after correcting their translations. Django skips fuzzy entries during compilation. Some Russian entries still need translation or review and fall back to English.

Then compile the catalogs from the same directory:

uv run python -m django compilemessages -l en -l ru

Keep the .po sources and compiled .mo files together in version control. Both are included in the distributed package.

Building

uv build
uv run twine check dist/*

The uv_build backend produces a wheel and source distribution in dist/, including the MIT license from LICENSE. The llms_manager package includes migrations, admin templates, static assets, and translation catalogs. With the current build configuration, tests/, .python-version, db.sqlite3, and uploaded media are excluded from both distributions.

Releasing

Before the first release:

  1. Create GitHub environments named testpypi and pypi.

  2. Configure a trusted publisher on both TestPyPI and PyPI, using these values:

    Field Value
    Project name django-llms-manager
    Owner KitKat-ru
    Repository django-llms-manager
    Workflow filename release.yml
    Environment testpypi on TestPyPI, pypi on PyPI

For each release, update version in pyproject.toml, commit the changes, and push a tag named v<version> (for example, v0.1.0).

The Release workflow checks that the tag matches the package version and runs the Checks workflow. After the checks pass, it publishes the same distributions to TestPyPI and then PyPI through Trusted Publishing.

Metadata

Release files for django-llms-manager 0.1.0

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-llms-manager 0.1.0
File Size Uploaded Provenance Actions
django_llms_manager-0.1.0.tar.gz 24.5 kB With provenance Details for django_llms_manager-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-llms-manager 0.1.0
File Interpreter ABI Platform Actions
django_llms_manager-0.1.0-py3-none-any.whl Python 3 none any Details for django_llms_manager-0.1.0-py3-none-any.whl

Total release size: 58.3 kB

Release files / django_llms_manager-0.1.0.tar.gz

Download URL django_llms_manager-0.1.0.tar.gz
Size 24.5 kB
Tags Source
SHA-256 checksum
How to use checksums
eda6b1c4f77f35ece2e18c3e10175e2fc65fcbaabe87345a36dd18c4a5eb8eac
BLAKE2b-256 checksum
How to use checksums
12ac94d940f7b11a56ba3a6f1942f239c1f1b6c4f83bcf6e1d2ebe545da4fbd4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / django_llms_manager-0.1.0-py3-none-any.whl

Download URL django_llms_manager-0.1.0-py3-none-any.whl
Size 33.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb0d6535e43c9967bdd11f95bda4fb47ace7f4fc0dad24199ffa1a04a8db2ff9
BLAKE2b-256 checksum
How to use checksums
7dcc9e680fb8f613c7a4fd7f5e0395c3b7b89e8eb2099fd6a7bf055c7cdadc23
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for django-llms-manager 0.1.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for django_llms_manager-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

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

0.1.0 This release

2 release files Full 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