---
since: 1.2.2
---

# DjangoPlay v1.2.2

DjangoPlay v1.2.2 is a feature release centered on the AI Assistant (`aicore`), which moves from a single, platform-configured provider to a flexible multi-provider, user-selectable model architecture with bring-your-own-key support, plus usage visibility and guardrails for admins. Alongside that, the local environment setup and fresh-install flow were overhauled and simplified, and a PostgreSQL extension bug affecting both fresh installs and existing deployments was found and fixed.

## Highlights

* Free model picker for the in-app AI Assistant, sourced live from OpenRouter's catalog
* Bring-your-own-key (BYOK) support: two personal profiles for local development, session/tab-scoped for production — keys are never persisted server-side
* Conversation history summarization for long chats, instead of a flat recent-message window
* New admin AI Usage Dashboard: request volume, success/error rates, last-used times, and per-provider/model breakdowns
* Per-provider-tier monthly token budgets and BYOK per-tab throttling
* `scripts/create_env.sh` (and a `curl | sudo bash` remote form) replaces manually copying environment file templates
* Fixed a PostgreSQL `pg_trgm` extension bug affecting both fresh installs and upgrades of existing databases
* All in-repo documentation (`docs/`) removed and migrated to a dedicated documentation site

## AI Assistant: Multi-Provider & Bring Your Own Model

### Added

* New `openrouter` provider, reusing the existing OpenAI-compatible client — no new provider class needed.
* Server-cached free-model catalog fetched from OpenRouter, filtered to free and text-only models, with optional admin allow/blocklist curation.
* Model dropdown in the chat widget header, with the last-picked model persisted across visits. Switching models mid-conversation requires explicit confirmation and starts a new session — no silent mid-session provider change.
* Bring-your-own-key support in two forms:

  * **Local development**: up to two named provider profiles in `~/.dplay/.secrets`, switchable with a one-line edit — no tracked settings file ever touched.
  * **Production**: a **"Use your own agent"** option in the chat header. The key lives only in that browser tab's `sessionStorage`, is sent as a request header rather than the request body, and is never written to the database or a log line. A cheap test call validates the key before it is accepted.
* Conversation history summarization: older messages are folded into a running summary in the background once a conversation grows past the recent-message window, so long conversations keep earlier context without resending the full transcript on every request.
* Admin **AI Usage Dashboard**: request counts, success/error rates, and last-used times by provider and model, with 7/30/90-day and all-time windows, plus a recent-errors view with full, copyable error messages.
* Per-provider-tier monthly token budgets — platform, free OpenRouter, and BYOK are now tracked and capped independently instead of sharing one number.
* Additional per-browser-tab request throttling for BYOK sessions, on top of the existing account-level rate limits.

### Changed

* Existing account-level rate limits continue to apply to BYOK sessions unchanged — the platform's only backstop against being used as a free relay is kept, even though BYOK tokens are billed to the user's own key.
* Chat transcripts (`ChatSession`/`ChatMessage`) are no longer exposed through generic admin discovery — the Usage Dashboard is now the intended surface for reviewing AI Assistant activity.
* The AI Assistant now displays as **AI Assistant** in the admin dashboard (a display-label override only — the underlying app and its URLs are unchanged).
* Proper icons and correctly-cased titles across the AI Assistant's admin pages.
* Usage Dashboard timestamps now display their timezone explicitly, removing ambiguity when reviewing activity across environments or users.

## Installation & Environment Configuration

### Added

* `scripts/create_env.sh` scaffolds all four `~/.dplay/` configuration files in one shot, with every key present and blank, and is safe to re-run.
* The environment scaffolding script is also available without a checkout via `curl -fsSL https://install.djangoplay.org/config | sudo bash`.
* The README was restructured around environment setup as a single documented prerequisite, followed by either the automated per-platform installer (fresh installs only) or the existing manual step-by-step path. The existing manual setup process itself is unchanged; the ordering now puts the fast path first.

### Fixed

* **PostgreSQL `pg_trgm` extension** was previously enabled by a manual `CREATE EXTENSION` step in the install scripts. This release moves extension handling into the database setup/migration flow. Two issues surfaced as a result of that change and are both fixed in this release:

  * On the per-platform installer scripts (`mac.sh`, `ubuntu.sh`, `windows.ps1`), which regenerate all migrations from the current model state on every run, the hand-authored extension-enabling migration was silently lost on regeneration because it is not derived from any model and therefore cannot be reconstructed by Django's migration autodetector. Fresh installs consequently failed with `operator class "gin_trgm_ops" does not exist`. The extension is now created directly as part of database provisioning in all three installer scripts, independently of migration regeneration.
  * On existing databases that had already applied later migrations under the old manual-extension-step migration graph, `migrate` refused to proceed with `InconsistentMigrationHistory`, because Django validates that every applied migration's current dependencies are also applied. See **Upgrade Notes** below if you're upgrading an existing database from v1.2.1 or earlier.

## Documentation

### Removed

* All in-repo documentation under `docs/` has been removed from this repository and migrated to a dedicated documentation site at [docs.djangoplay.org](https://docs.djangoplay.org/). This includes the former architecture, per-app, infrastructure, and prior-release changelog documents.
* The main `README.md` was correspondingly trimmed — deep per-app detail, starting with `aicore`, now links out to the documentation site rather than living inline.

## Upgrade Notes

v1.2.2 is intended as a feature upgrade from v1.2.1.

**If you're upgrading an existing database** (not a fresh install), the `pg_trgm` migration fix above requires a one-time manual reconciliation step before `migrate` will run, because the migration now has a dependency that did not exist when your database last migrated.

From a Django shell:

```python
from django.db import connection
from django.db.migrations.recorder import MigrationRecorder

with connection.cursor() as cur:
    cur.execute("SELECT 1 FROM pg_extension WHERE extname = 'pg_trgm'")
    assert cur.fetchone(), "pg_trgm not actually installed -- investigate before proceeding"

MigrationRecorder(connection).record_applied("locations", "0001_1_enable_pg_trgm")
```

Then run:

```bash
python manage.py migrate
```

as normal.

This is a one-time step per existing database. New databases created via the installer or a fresh `migrate` are unaffected.

**Fresh installs** (new database, new checkout) are unaffected by the above and require no manual steps — the installer scripts now handle the `pg_trgm` extension automatically.

## Summary

DjangoPlay v1.2.2 turns the AI Assistant into a multi-provider, user-configurable feature — free model selection, bring-your-own-key support for both local development and production, conversation history summarization, and an admin Usage Dashboard with per-tier budgets and throttling.

The release also consolidates local environment setup into a single scaffolding script, fixes a `pg_trgm` migration/provisioning issue affecting both fresh and existing databases, and moves all project documentation out of the repository to a dedicated documentation site.

Full details for each change are available in the accompanying design documentation:

https://docs.djangoplay.org/projects/djangoplay-web/apps/aicore/