This guide explains how to install ai_hub as a reusable Django app in any host project.

ai_hub is intentionally self-contained. A host project installs the app, runs its migrations, configures providers and models in Django Admin, then connects domain-specific workflows through a thin adapter.

• Python 3.12 or newer.
• Django 5.2 LTS or newer, below Django 7.
• SQLite for local development, or PostgreSQL for production.
• A Django admin user.
• Static files configured for Django Admin.
• Provider credentials stored in environment variables.

The app can work with local models, hosted providers, or custom provider adapters. Provider credentials should never be stored directly in the database.

Copy or install the ai_hub package into the Django project.

Example layout:

my_project/
    manage.py
    my_project/
        settings.py
        urls.py
    ai_hub/
        apps.py
        models.py
        admin.py

Add the app to INSTALLED_APPS.

INSTALLED_APPS = [
    # ...
    "ai_hub",
]

The technical app label is ai_hub. The visible admin name is AI Hub.

Add the internal URLs if the host project needs staff-only execution endpoints.

from django.urls import include, path

urlpatterns = [
    # ...
    path("ai-hub/", include("ai_hub.urls")),
]

The most important URL is the internal execution endpoint:

/ai-hub/internal/execution-session/run/

Use it when the host project wants a staff-only HTTP trigger for execution sessions. If the host project calls services directly from Python, including these URLs is optional.

python manage.py migrate ai_hub

After migrating, the database should contain the reusable AI tables, including the core configuration and execution tables:

• ai_hub_providerconfig
• ai_hub_modelconfig
• ai_hub_agentprofile
• ai_hub_pipelinedefinition
• ai_hub_executionsession
• ai_hub_executionsteprun

and the GAME domain tables (ai_hub_gameworkspace, ai_hub_gamegoal, ai_hub_gameactionrun, ai_hub_gamememoryentry, and related). Run python manage.py migrate ai_hub again after pulling updates; migrations are additive.

python manage.py createsuperuser

The bundled development setup generates the initial admin password instead of using a shared default. Set DJANGO_SUPERUSER_PASSWORD before running setup only when automation needs a predetermined value.

For DEBUG=False, provide a strong SECRET_KEY. Secure redirect and cookie settings default to enabled in production mode. Configure SECURE_HSTS_SECONDS, SECURE_HSTS_INCLUDE_SUBDOMAINS, and SECURE_HSTS_PRELOAD only after confirming the complete domain and all included subdomains are permanently HTTPS.

The GAME subsystem is gated by feature flags (AI_HUB_GAME_*_ENABLED). They default to enabled in this repo, but the reusable safety default is fail-closed — if you adopt ai_hub into a new project and a flag is disabled, GAME services raise a clear error. Enable the capabilities you use. See 03_CONFIGURATION.md for the full list.

Then open:

/admin/ai_hub/

This is the main AI Hub entry point. Users should normally begin here instead of jumping directly into raw model lists.

The admin experience depends on app-specific CSS and JavaScript. In production or any DEBUG=False environment, run:

python manage.py collectstatic

Confirm that these files are served:

ai_hub/admin/ai_hub_admin.css
ai_hub/admin/ai_hub_admin.js

If the page renders without the guided UI styling, the most likely cause is a static files deployment issue.

Open:

/admin/ai_hub/providerconfig/add/

Recommended first fields:

• Name: Local Ollama or OpenAI Production.
• Provider type: choose the matching provider adapter.
• Base URL: local or remote endpoint when required.
• API key env var: the environment variable name, not the secret itself.
• Default timeout: use a realistic value for slow models.
• Is active: enabled only when the provider is ready.

Example:

Name: Local Ollama
Provider type: Ollama
Base URL: http://localhost:11434
Default timeout: 180
Is active: yes

Open:

/admin/ai_hub/modelconfig/add/

Recommended fields:

• Provider: the active provider.
• Display name: a friendly name for users.
• Model name: the exact provider model identifier.
• Temperature default: low for structured outputs, higher for creative text.
• Max tokens default: large enough for the expected output contract.
• Supports tools: only enable this when the model/runtime can use tools.
• Is active: enabled only when the model is installed and reachable.

Example:

Display name: Qwen 3 8B
Model name: qwen3:8b
Temperature default: 0.2
Max tokens default: 12000
Supports tools: no

Open:

/admin/ai_hub/agentprofile/add/

Minimum useful setup:

• Choose an active model.
• Give the agent a clear role.
• Write a focused system prompt.
• Add an output contract if the result must be structured JSON.
• Attach knowledge collections only when the agent needs curated context.
• Attach tools only when the runtime can execute them safely.

Good agent names are concrete:

Input Normalizer
Evidence Extractor
Report Writer
Support Triage Agent
GAME Planning Agent

AI Hub has two execution workspaces.

Use Orchestrator when the workflow has known steps:

input -> extract -> analyze -> write -> final output

Use GAME when one agent should work autonomously toward a goal:

goal -> decision loop -> observations -> memory -> finish or stop

Both workspaces use the same providers, models, agents, knowledge and tools. The separation is a UX and operating-model separation, not a separate database.

1. Create one active provider.
2. Create one active model.
3. Create one active agent.
4. Create a pipeline with that agent as the entry agent.
5. Add one pipeline step.
6. Create an execution session with runtime_kind = orchestrator.
7. Run it from the admin or internal endpoint.
8. Confirm that step logs appear under ExecutionStepRun.

1. Create one active provider.
2. Create one active model.
3. Create one active GAME-oriented agent.
4. Open the GAME workspace.
5. Create a GAME session with a small goal.
6. Run the session.
7. Confirm that iterations appear as step runs.
8. Confirm that the session ends as success, failed, waiting or stopped.

Run:

python manage.py check
python manage.py test ai_hub

For a host project that already integrates with AI Hub, also run that app's tests:

python manage.py test your_host_app ai_hub

• ai_hub is installed directly in INSTALLED_APPS.
• Migrations are applied.
• Admin static files are collected and served.
• Provider secrets live in environment variables.
• Provider timeouts match real model latency.
• Models are marked active only when available.
• Agents have clear prompts and contracts.
• Pipelines have ordered steps.
• GAME sessions have a goal and an entry agent.
• Host-specific persistence lives in the host app, not inside ai_hub.