Django Lucy Assist

Assistant IA intelligent base sur Claude (Anthropic), integrable dans n'importe quelle application Django.

Installation

pip install django-lucy-assist

Configuration

1. Ajouter l'application a INSTALLED_APPS

INSTALLED_APPS = [
    ...
    'lucy_assist',
]

2. Configurer le jeton projet Lucy

Un seul secret dans le .env : le jeton d'appairage du projet, généré par Lucy (fiche projet > Intégrations). C'est le même que celui du module de retour.

# ======================================== LUCY ASSIST ========================================
LUCY_PROJET_TOKEN=jeton-d-appairage-du-projet

Puis dans votre settings.py :

#############################################################################################################
# Lucy Assist
LUCY_PROJET_TOKEN = env('LUCY_PROJET_TOKEN', default=None)
LUCY_ASSIST = {'PROJECT_APPS_PREFIX': 'apps.'}

Ce jeton permet à Lucy Assist, de serveur à serveur uniquement :

• de récupérer le jeton GitLab du projet (stocké chiffré dans Lucy) et l'URL de l'instance GitLab ; le dépôt est déduit du jeton (un jeton de projet GitLab n'ouvre qu'un dépôt) ;
• de connaître le chef de projet à prévenir (feedbacks, bugs détectés) ;
• de demander la facture d'achat de tokens, envoyée par e-mail au client.

Plus de GITLAB_URL, GITLAB_TOKEN, GITLAB_PROJECT_ID, SIREN_CLIENT ni ANTHROPIC_LUCY_API_KEY dans le .env.

3. Ajouter les URLs

# urls.py
from django.urls import path, include

urlpatterns = [
    ...
    path('lucy-assist/', include('lucy_assist.urls')),
]

4. Ajouter le context processor

# settings.py
TEMPLATES = [
    {
        ...
        'OPTIONS': {
            'context_processors': [
                ...
                'lucy_assist.context_processors.lucy_assist_context',
            ],
        },
    },
]

5. Inclure le template dans votre base.html

<!-- templates/base.html -->
{% include 'lucy_assist/chatbot_sidebar.html' %}

6. Executer les migrations

python manage.py migrate lucy_assist

7. Configurer l'IA dans l'admin

Dans l'admin Django, Configuration Lucy Assist > Intelligence artificielle :

• Clé API Claude (sk-ant-…) : stockée chiffrée en base (Fernet, clé dérivée du SECRET_KEY). Si le SECRET_KEY change, la clé devient illisible : il suffit de la ressaisir.
• Modèle Claude : claude-haiku-5-5 par défaut.

Le prix de vente se règle dans la même page (10 € HT par million de tokens par défaut), ainsi que la couleur de marque (marque blanche).

Utilisation

Une fois installe et configure, Lucy Assist apparaitra automatiquement sur toutes les pages de votre application avec un bouton flottant en bas a droite.

Fonctionnalites

• Chat IA contextuel : Lucy comprend le contexte de la page actuelle
• Actions CRUD : Lucy peut creer, modifier, rechercher et supprimer des objets
• Analyse de bugs : Connexion a GitLab pour analyser les problemes signales
• Historique des conversations : Sauvegarde automatique des conversations
• Gestion des tokens : Suivi de la consommation des tokens Claude

Configuration avancee

Modele de base personnalise

Si vous utilisez un modele de base personnalise avec des champs d'audit (created_date, updated_date, etc.), vous pouvez le configurer :

LUCY_ASSIST = {
    'BASE_MODEL': 'mon_app.models.MonModeleBase',
}

Modele Claude

Le modèle se règle dans l'admin (Configuration Lucy Assist), claude-haiku-5-5 par défaut.

Multi-tenant, actions et contexte utilisateur

LUCY_ASSIST = {
    # Manager filtrant les donnees de l'utilisateur connecte, utilise pour toutes les lectures
    'QUERYSET_MANAGER': 'user_filter',
    # Mode strict (defaut) : un modele sans ce manager n'est pas lisible par Lucy
    'QUERYSET_MANAGER_STRICT': True,
    # Fonction du middleware ThreadLocal lue par ces managers ('module' ou 'module:fonction')
    'THREAD_LOCAL_MODULE': 'mon_projet.middleware:set_current_user',
    # Rejouer les controles d'acces des vues (mixins de connexion, permission, module, role)
    # avant toute lecture : requete OPTIONS simulee sur la page liste / detail, sans rendu
    'ENFORCE_VIEW_ACCESS': True,
    # Recapitulatif valide par l'utilisateur avant toute creation / modification
    'CONFIRM_BEFORE_WRITE': True,
    # Sans vue de creation/modification decouverte : repli sur un ModelForm
    # (permission add/change exigee, erreurs renvoyees champ par champ). [] pour desactiver
    'FORM_FALLBACK_ACTIONS': ['create', 'update'],
    # Tours d'outils maximum avant une reponse texte forcee
    'MAX_TOOL_ITERATIONS': 8,
    # Description de l'utilisateur dans le prompt : fonction (user) -> dict (optionnel)
    'USER_CONTEXT_CALLABLE': 'mon_app.lucy.contexte_utilisateur',
}

Sans USER_CONTEXT_CALLABLE, Lucy lit le nom complet (get_full_name(), full_name ou prenom + nom, jamais l'email a la place du nom), l'email, le role (role ou groupes) et l'entreprise (user.entreprise) de l'utilisateur, ainsi que la date du jour.

La confirmation avant ecriture s'appuie sur le cache Django : avec plusieurs processus (gunicorn, uwsgi), configurez un cache partage (Redis, base de donnees).

Personnalisation des questions frequentes

LUCY_ASSIST = {
    'QUESTIONS_FREQUENTES_DEFAULT': [
        "Comment creer un nouveau membre ?",
        "Comment effectuer un paiement ?",
        "Comment exporter des donnees ?",
    ],
}

API

Lucy Assist expose plusieurs endpoints API :

• GET /lucy-assist/api/conversations - Liste des conversations
• POST /lucy-assist/api/conversations - Creer une conversation
• GET /lucy-assist/api/conversations/<id> - Detail d'une conversation
• POST /lucy-assist/api/conversations/<id>/messages - Ajouter un message
• POST /lucy-assist/api/conversations/<id>/chat - Generer une reponse (streaming)
• GET /lucy-assist/api/tokens/status - Statut des tokens

Licence

Revolucy

Lancer le serveur de test

python test_project/manage.py runserver

Ensuite, accède à :

• Page de test : http://localhost:8000/
• Module retour client : http://localhost:8000/retour/
• Admin Django : http://localhost:8000/admin/
• Lancement des tests sur les questions : python manage.py test_lucy

Deploiement Pypi

1. docker-compose exec django pip install build twine
2. docker-compose exec django python -m build
3. docker-compose exec django python -m twine upload dist/*
4. Indiquer le token present dans 1Password