django-llms-manager 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. django_llms_manager-0.1.0/LICENSE +21 -0
  2. django_llms_manager-0.1.0/PKG-INFO +370 -0
  3. django_llms_manager-0.1.0/README.md +336 -0
  4. django_llms_manager-0.1.0/llms_manager/__init__.py +0 -0
  5. django_llms_manager-0.1.0/llms_manager/admin.py +513 -0
  6. django_llms_manager-0.1.0/llms_manager/apps.py +8 -0
  7. django_llms_manager-0.1.0/llms_manager/exceptions.py +2 -0
  8. django_llms_manager-0.1.0/llms_manager/forms.py +73 -0
  9. django_llms_manager-0.1.0/llms_manager/locale/en/LC_MESSAGES/django.mo +0 -0
  10. django_llms_manager-0.1.0/llms_manager/locale/en/LC_MESSAGES/django.po +318 -0
  11. django_llms_manager-0.1.0/llms_manager/locale/ru/LC_MESSAGES/django.mo +0 -0
  12. django_llms_manager-0.1.0/llms_manager/locale/ru/LC_MESSAGES/django.po +322 -0
  13. django_llms_manager-0.1.0/llms_manager/migrations/0001_initial.py +155 -0
  14. django_llms_manager-0.1.0/llms_manager/migrations/__init__.py +0 -0
  15. django_llms_manager-0.1.0/llms_manager/models.py +216 -0
  16. django_llms_manager-0.1.0/llms_manager/static/llms_manager/admin.css +71 -0
  17. django_llms_manager-0.1.0/llms_manager/templates/admin/llms_manager/base.html +18 -0
  18. django_llms_manager-0.1.0/llms_manager/templates/admin/llms_manager/document_change_form.html +8 -0
  19. django_llms_manager-0.1.0/llms_manager/templates/admin/llms_manager/editor.html +27 -0
  20. django_llms_manager-0.1.0/llms_manager/templates/admin/llms_manager/history.html +43 -0
  21. django_llms_manager-0.1.0/llms_manager/templates/admin/llms_manager/publication_change_form.html +82 -0
  22. django_llms_manager-0.1.0/llms_manager/templates/admin/llms_manager/revision.html +25 -0
  23. django_llms_manager-0.1.0/llms_manager/urls.py +15 -0
  24. django_llms_manager-0.1.0/llms_manager/utils.py +24 -0
  25. django_llms_manager-0.1.0/llms_manager/views.py +43 -0
  26. django_llms_manager-0.1.0/pyproject.toml +82 -0
  27. django_llms_manager-0.1.0/pyproject.toml.orig +75 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Artem Fabrikov
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,370 @@
1
+ Metadata-Version: 2.4
2
+ Name: django-llms-manager
3
+ Version: 0.1.0
4
+ Summary: Manage llms.txt content for AI assistants through the Django admin.
5
+ Author: Artem Fabrikov
6
+ Author-email: Artem Fabrikov <a.fabrikov1406@yandex.ru>
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 1 - Planning
10
+ Classifier: Environment :: Web Environment
11
+ Classifier: Framework :: Django
12
+ Classifier: Framework :: Django :: 4.2
13
+ Classifier: Framework :: Django :: 5.0
14
+ Classifier: Framework :: Django :: 5.1
15
+ Classifier: Framework :: Django :: 5.2
16
+ Classifier: Framework :: Django :: 6.0
17
+ Classifier: Framework :: Django :: 6.1
18
+ Classifier: Intended Audience :: Developers
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Programming Language :: Python :: 3.14
26
+ Classifier: Programming Language :: Python :: 3.15
27
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
28
+ Requires-Dist: django>=4.2
29
+ Requires-Python: >=3.10
30
+ Project-URL: Homepage, https://github.com/KitKat-ru/django-llms-manager
31
+ Project-URL: Repository, https://github.com/KitKat-ru/django-llms-manager
32
+ Project-URL: Issues, https://github.com/KitKat-ru/django-llms-manager/issues
33
+ Description-Content-Type: text/markdown
34
+
35
+ # django-llms-manager
36
+
37
+ [![Checks](https://github.com/KitKat-ru/django-llms-manager/actions/workflows/tests.yml/badge.svg)](https://github.com/KitKat-ru/django-llms-manager/actions/workflows/tests.yml)
38
+ [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
39
+
40
+ Manage `llms.txt` and `llms-full.txt` content for AI assistants through the Django
41
+ admin. Edit Markdown or import a UTF-8 file, save revisions, review changes, and
42
+ publish a selected version at the site root or in a nested directory.
43
+
44
+ Requires Python 3.10+ and Django 4.2+. Supported Python/Django combinations follow
45
+ [Django's compatibility table](https://docs.djangoproject.com/en/stable/faq/install/#what-python-version-can-i-use-with-django).
46
+
47
+ CI is configured to check all 22 officially supported combinations of the declared
48
+ Python and Django series, using the latest available patch release of each Django
49
+ series:
50
+
51
+ | Python | Django series |
52
+ | --- | --- |
53
+ | 3.10 | 4.2, 5.0, 5.1, 5.2 |
54
+ | 3.11 | 4.2, 5.0, 5.1, 5.2 |
55
+ | 3.12 | 4.2, 5.0, 5.1, 5.2, 6.0, 6.1 |
56
+ | 3.13 | 5.1, 5.2, 6.0, 6.1 |
57
+ | 3.14 | 5.2, 6.0, 6.1 |
58
+ | 3.15 | 6.1 |
59
+
60
+ ## Setup
61
+
62
+ To use a local checkout in an existing Django project managed with uv, add it as a
63
+ [path dependency](https://docs.astral.sh/uv/concepts/projects/dependencies/#path):
64
+
65
+ ```bash
66
+ uv add /path/to/django-llms-manager
67
+ ```
68
+
69
+ Add the application to a Django project with the admin enabled:
70
+
71
+ ```python
72
+ INSTALLED_APPS = [
73
+ ...,
74
+ "llms_manager",
75
+ ]
76
+ ```
77
+
78
+ Mount the publication routes at the site root, after specific application routes
79
+ and before any catch-all route:
80
+
81
+ ```python
82
+ from django.urls import include, path
83
+
84
+ urlpatterns = [
85
+ ...,
86
+ path("", include("llms_manager.urls")),
87
+ ]
88
+ ```
89
+
90
+ Apply the included migrations using the host project's settings:
91
+
92
+ ```bash
93
+ uv run python manage.py migrate
94
+ ```
95
+
96
+ Open **llms** in the Django admin to create named documents. Each document has its
97
+ own editor and revision history. Open **Publications** to configure their public
98
+ addresses and select the revisions served there.
99
+
100
+ ## Revisions and publishing
101
+
102
+ 1. Create or select a document and open its **Editor** or **Revision history**.
103
+ 2. Edit the complete Markdown document, or use **Load file into editor** to import
104
+ a UTF-8 file. Importing replaces the editor contents without saving a revision.
105
+ 3. **Save revision** creates an immutable file snapshot belonging to that document.
106
+ Revisions are numbered from 1 independently within each document.
107
+ 4. Create or open a **Publication**. Its address consists of a directory and a file
108
+ name selected from `llms.txt` and `llms-full.txt`.
109
+ 5. In the publication card, select a document and click **Show revisions**. Select
110
+ any of its saved revisions and click **Review revision**. Selection and review
111
+ are available before saving a new publication; the entered address is preserved.
112
+ 6. Review the content and diff against the revision currently published at this
113
+ particular address. If the address is new or has changed, click **Save address**;
114
+ the selected document and revision are kept. Then click **Publish revision**.
115
+ Both buttons are at the top of the card. Publishing becomes available after
116
+ reviewing a revision and saving the address. **Save address** only saves the
117
+ address; changing the selection or reviewing a diff does not publish anything.
118
+
119
+ When the selected revision is already published at this address, the card shows
120
+ its status, complete content, and public link. The diff is hidden.
121
+
122
+ | Directory | File name | Public address |
123
+ | --- | --- | --- |
124
+ | `/` | `llms.txt` | `/llms.txt` |
125
+ | `/` | `llms-full.txt` | `/llms-full.txt` |
126
+ | `/courses/python/` | `llms.txt` | `/courses/python/llms.txt` |
127
+ | `/courses/python/` | `llms-full.txt` | `/courses/python/llms-full.txt` |
128
+
129
+ Each directory/file-name pair is unique. Directory input is normalized: for
130
+ example, `courses/python` becomes `/courses/python/`. Editing a saved directory or
131
+ file name changes the public URL while keeping its selected revision.
132
+
133
+ Publication changes are independent for each address. If its selected revision
134
+ has changed since the review, publication is rejected and the updated diff is
135
+ shown. Updating another address does not invalidate the review.
136
+
137
+ The revision history records the author and creation date. Use **Edit as new
138
+ revision** to continue working from a saved snapshot. To restore an older version,
139
+ select it in the publication card, review its diff, and publish it again. Any saved
140
+ revision can be selected, including an older revision of a different document.
141
+ Publication actions are recorded in the publication's Django admin **History**.
142
+
143
+ Public files are available without logging in and return the selected content as
144
+ `text/plain; charset=utf-8`. The publication view accepts `GET` and `HEAD` and only
145
+ reads existing publications; requesting a URL does not create documents, revisions,
146
+ or publications.
147
+ A configured address without a selected revision returns an empty response with
148
+ status `200`. An unconfigured address returns `404`. The routes match only the
149
+ two supported file names, at the root or in nested directories.
150
+ Markdown is displayed as text; the application does not enforce a section schema.
151
+ Links between root and nested files belong to the Markdown content. The library
152
+ does not automatically assemble `llms-full.txt` from other publications.
153
+
154
+ The `view_document` permission allows viewing document history and previews.
155
+ The `add_document` permission allows creating documents. The `change_document`
156
+ permission allows renaming documents and importing and saving revisions.
157
+
158
+ The `view_publication` permission allows viewing publication cards and history.
159
+ The `add_publication` permission allows configuring new addresses, and
160
+ `change_publication` allows changing addresses and confirming publications.
161
+ Selecting and publishing document revisions also requires `view_document` or
162
+ `change_document`. Removing an address through the standard `delete_publication`
163
+ permission does not delete its document or revision files.
164
+ Documents and revisions cannot be deleted through the library's admin interface.
165
+
166
+ Each `Publication` points to one selected revision; its document is determined
167
+ through `Revision.document`. The same revision can be served at multiple addresses.
168
+ Changing a publication preserves all documents, their revisions, and their files.
169
+ Address uniqueness uses a normal constraint on directory and file name, without
170
+ conditional indexes.
171
+
172
+ ## File storage
173
+
174
+ Revision files use Django's default storage, selected by `STORAGES["default"]`.
175
+ The database stores file names and revision metadata. Each snapshot has a unique
176
+ key such as `llms_manager/<uuid>.txt`.
177
+
178
+ Public addresses and storage keys are independent. For example,
179
+ `/courses/python/llms-full.txt` serves the file referenced by that publication's
180
+ revision. The directory and public file name do not determine the storage key.
181
+ Each revision gets a new key, so saving another revision preserves earlier files.
182
+
183
+ For local storage, configure `MEDIA_ROOT`, for example:
184
+
185
+ ```python
186
+ MEDIA_ROOT = BASE_DIR / "media"
187
+ ```
188
+
189
+ For S3, install `django-storages[s3]` in the host project and configure its
190
+ [S3 backend](https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html),
191
+ for example:
192
+
193
+ ```python
194
+ STORAGES = {
195
+ "default": {
196
+ "BACKEND": "storages.backends.s3.S3Storage",
197
+ "OPTIONS": {"bucket_name": "my-bucket"},
198
+ },
199
+ "staticfiles": {
200
+ "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
201
+ },
202
+ }
203
+ ```
204
+
205
+ Credentials and other backend options belong to the host project's configuration.
206
+ The library reads files through the Storage API and serves their content at the
207
+ configured public endpoint. Other file fields using the default storage share
208
+ this backend. Access to storage objects themselves follows the project's storage
209
+ configuration.
210
+
211
+ Database and file storage are separate systems. Keep both when backing up or
212
+ moving the application. When changing storage backends, copy existing revision
213
+ files while preserving the keys stored in the database. A database rollback in
214
+ an enclosing transaction can leave an unreferenced file in storage.
215
+
216
+ ## Caching
217
+
218
+ Public file content uses [Django's default cache](https://docs.djangoproject.com/en/4.2/topics/cache/#accessing-the-cache)
219
+ from `CACHES`. Set the lifetime in the host project's settings:
220
+
221
+ ```python
222
+ LLMS_MANAGER_CACHE_TIMEOUT = 60 # Seconds; 0 or None disables caching.
223
+ ```
224
+
225
+ If the setting is absent, the default is 60 seconds. Set `0` or `None` to disable
226
+ caching. Positive values must be integers. Invalid values, including strings,
227
+ booleans, floats, and negative integers, disable caching and emit a `RuntimeWarning`
228
+ when a published revision is requested. Repeated warnings follow the project's
229
+ [Python warning filters](https://docs.python.org/3/library/warnings.html#the-warnings-filter).
230
+
231
+ Each request looks up the publication in the database to determine its current
232
+ revision. The revision's text is read from the cache,
233
+ or loaded from Storage and cached on a miss. Publishing another revision selects
234
+ a different cache key, so the next request serves the newly selected content.
235
+ Restoring an earlier revision can reuse its cached text until that entry expires.
236
+ The same revision can share its cached text across multiple public addresses.
237
+
238
+ This caches revision text on the server; it does not add HTTP cache headers.
239
+ Address changes and deletions take effect on the next request. Admin previews
240
+ continue to read files directly from Storage.
241
+
242
+ ## Development
243
+
244
+ Development uses Python 3.13 and [uv](https://docs.astral.sh/uv/). Run these commands
245
+ from the repository root to prepare the environment:
246
+
247
+ ```bash
248
+ uv sync
249
+ uv run pre-commit install
250
+ ```
251
+
252
+ The `.python-version` file selects Python 3.13 for development; package support
253
+ starts at Python 3.10 as declared in `pyproject.toml`.
254
+ [`uv sync`](https://docs.astral.sh/uv/concepts/projects/sync/) synchronizes `.venv/`
255
+ with the project dependencies and `uv.lock`. The `dev` dependency group includes
256
+ the `test` group with pytest and pytest-django. Pytest uses `tests.settings`.
257
+
258
+ `tests/` contains a minimal Django project with the admin enabled and a SQLite
259
+ database stored in `db.sqlite3`. It is not part of the distributed package.
260
+
261
+ To run the project locally:
262
+
263
+ ```bash
264
+ export DJANGO_SETTINGS_MODULE=tests.settings
265
+ uv run python -m django migrate
266
+ uv run python -m django createsuperuser
267
+ uv run python -m django runserver
268
+ ```
269
+
270
+ Open [the admin](http://127.0.0.1:8000/admin/) or
271
+ [llms.txt](http://127.0.0.1:8000/llms.txt). Before a root publication is created,
272
+ `/llms.txt` returns `404`. After saving its address, it returns an empty file until
273
+ a revision is published. Local revision files are stored in `media/llms_manager/`.
274
+ The development project defaults to Russian (`LANGUAGE_CODE = "ru"` in
275
+ `tests/settings.py`); set it to `"en"` for English.
276
+
277
+ Run the checks from the repository root:
278
+
279
+ ```bash
280
+ uv run ruff check .
281
+ uv run ruff format --check .
282
+ uv run python -m django check --settings=tests.settings
283
+ uv run python -m django makemigrations llms_manager --check --dry-run --settings=tests.settings
284
+ uv run pytest
285
+ ```
286
+
287
+ After model changes, generate and review migrations with
288
+ `uv run python -m django makemigrations llms_manager --settings=tests.settings`.
289
+ Then apply them with `uv run python -m django migrate --settings=tests.settings`.
290
+ The initial setup uses the included migrations.
291
+
292
+ Ruff handles linting, import sorting, and formatting through pre-commit and targets
293
+ Python 3.10 syntax. To run all hooks, including automatic fixes and formatting:
294
+
295
+ ```bash
296
+ uv run pre-commit run --all-files
297
+ ```
298
+
299
+ Pre-commit checks files tracked by Git. The direct Ruff commands above also cover
300
+ new Python files before they are tracked.
301
+
302
+ CI builds the distributions, checks their metadata, installs the wheel with each
303
+ Python/Django pair in the matrix, checks for missing migrations, and runs the tests
304
+ from outside the source directory.
305
+
306
+ ## Translations
307
+
308
+ English (`en`) and Russian (`ru`) catalogs are stored in `llms_manager/locale/`.
309
+ The interface uses the active Django language. To use Russian by default, set
310
+ `LANGUAGE_CODE = "ru"` in the host project with `USE_I18N = True`.
311
+
312
+ To update the catalogs, run these commands with GNU gettext installed:
313
+
314
+ ```bash
315
+ cd llms_manager
316
+ uv run python -m django makemessages -l en -l ru
317
+ ```
318
+
319
+ Edit `msgstr` values in `locale/*/LC_MESSAGES/django.po`. Review entries marked
320
+ `fuzzy` and remove that flag after correcting their translations.
321
+ [Django skips fuzzy entries during compilation](https://docs.djangoproject.com/en/stable/topics/i18n/translation/#message-files).
322
+ Some Russian entries still need translation or review and fall back to English.
323
+
324
+ Then compile the catalogs from the same directory:
325
+
326
+ ```bash
327
+ uv run python -m django compilemessages -l en -l ru
328
+ ```
329
+
330
+ Keep the `.po` sources and compiled `.mo` files together in version control.
331
+ Both are included in the distributed package.
332
+
333
+ ## Building
334
+
335
+ ```bash
336
+ uv build
337
+ uv run twine check dist/*
338
+ ```
339
+
340
+ The `uv_build` backend produces a wheel and source distribution in `dist/`,
341
+ including the MIT license from `LICENSE`. The `llms_manager` package includes
342
+ migrations, admin templates, static assets, and translation catalogs. With the
343
+ current [build configuration](https://docs.astral.sh/uv/concepts/build-backend/#file-inclusion-and-exclusion),
344
+ `tests/`, `.python-version`, `db.sqlite3`, and uploaded media are excluded from both
345
+ distributions.
346
+
347
+ ## Releasing
348
+
349
+ Before the first release:
350
+
351
+ 1. Create GitHub environments named `testpypi` and `pypi`.
352
+ 2. Configure a trusted publisher on both
353
+ [TestPyPI](https://test.pypi.org/manage/account/publishing/) and
354
+ [PyPI](https://pypi.org/manage/account/publishing/), using these values:
355
+
356
+ | Field | Value |
357
+ | --- | --- |
358
+ | Project name | `django-llms-manager` |
359
+ | Owner | `KitKat-ru` |
360
+ | Repository | `django-llms-manager` |
361
+ | Workflow filename | `release.yml` |
362
+ | Environment | `testpypi` on TestPyPI, `pypi` on PyPI |
363
+
364
+ For each release, update `version` in `pyproject.toml`, commit the changes, and
365
+ push a tag named `v<version>` (for example, `v0.1.0`).
366
+
367
+ The Release workflow checks that the tag matches the package version and runs
368
+ the Checks workflow. After the checks pass, it publishes the same distributions
369
+ to TestPyPI and then PyPI through
370
+ [Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/).