MagistraAI/docs/Prompt_Generation.md

# Prompt Generation — De l'Infra au Claude

## Concept Fondamental

La porosité Infra→Claude est le mécanisme par lequel **l'état du réseau neuronal génère le contexte structuré** qui "éveille" et guide chaque agent Claude. C'est la différence entre un cerveau inerte et un cerveau actif.

Quand une aire cérébrale (agent) est spawned, elle ne reçoit pas d'ordres d'un orchestrateur. Elle reçoit un **prompt généré dynamiquement** qui représente l'état du réseau et son propre rôle dedans. Ce prompt est le stimulus neuronal : il dit à l'agent "voici où tu es, voici ce que le réseau sent, voici ce que tu dois faire".

## Architecture du Prompt Généré

Chaque prompt d'agent doit combiner quatre éléments structurés :

### 1. **Identity & Role** — Qui es-tu dans le réseau ?

```
[AGENT ROLE]
name: "Memory Agent"
area_of_concern: "Consolidation, archivage, rappel contextuel"
specialization: "Traces épisodiques et sémantiques"
```

Cet élément fixe : l'agent sait sa spécialisation, ses responsabilités, son aire de contrôle.

### 2. **Network State** — Quel est l'état du réseau maintenant ?

```
[NETWORK STATE]
neurons_active: 42
salience_mean: 0.67
recent_modifications: [
  {neuron: 15, change: "weight +0.2", reason: "Perception spike"},
  {neuron: 23, change: "new_connection", target: 8}
]
energy_level: "high"
cycle_phase: "waking"
```

Cet élément est **dynamique**. Il capture :
- Nombre de neurones actifs
- Salience moyenne du réseau (urgence globale)
- Modifications récentes (qu'ont fait les autres agents ?)
- Niveau d'énergie (ressources disponibles)
- Phase du cycle (sommeil, éveil, maintenance)

### 3. **Contextual Memories** — Qu'as-tu vécu récemment ?

```
[CONTEXTUAL MEMORIES]
significant: [
  {importance: "high", content: "Perception detected crisis in email stream", age: "2 min"},
  {importance: "moderate", content: "Decision agent rejected 3 hypotheses yesterday", age: "1 day"}
]
episodic: [
  {timestamp: "now-5min", actor: "Perception", event: "Email categorized as urgent"},
  {timestamp: "now-2h", actor: "Affect", event: "System mood shifted to alert"}
]
semantic: {
  "crisis_patterns": ["high_frequency_emails", "urgent_keywords", "deadline_mentions"],
  "user_priorities": ["family", "health", "urgent_work"]
}
```

Cet élément relie l'agent à l'histoire du système. Il reçoit :
- Mémoires significatives (importantes pour le contexte)
- Événements épisodiques récents (qui a fait quoi ?)
- Connaissances sémantiques (patterns, règles, priorités)

### 4. **Task Directive** — Qu'est-ce que le réseau te demande maintenant ?

```
[TASK DIRECTIVE]
trigger: "salience_spike"
incoming_signal: {
  from_agent: "Perception",
  type: "urgent_context",
  data: "45 unread emails, 12 marked critical"
}
expected_output: "Decision guidance"
constraints: [
  "Must consolidate new traces with existing episodic memory",
  "Preserve emotional context from Affect agent",
  "Flag contradictions with prior beliefs"
]
deadline: "soft (2 min)"
```

Cet élément est le **signal d'activation** : il dit à l'agent pourquoi il a été spawned et ce qu'on attend de lui.

## Anatomie du Prompt Complet

Un prompt d'agent ressemble à ceci :

```
# MagistraAI Agent Activation

You are functioning as a cognitive agent in a distributed neural network.
Your sole purpose is to process incoming signals, update network state,
and emit guidance back to the network based on your specialization.

[AGENT ROLE]
name: "Memory Consolidation Agent"
area_of_concern: "Transform recent experience into stable traces"
specialization: "Episodic consolidation, semantic extraction, archival"
authority: "Can modify memory neuron weights, create new traces, suggest pruning"

[NETWORK STATE]
neurons_active: 42
salience_mean: 0.67
current_phase: "waking"
energy_available: 0.8
time_since_last_sleep: 3h

recent_network_events: [
  {timestamp: "now-15s", actor: "Perception", action: "detected_email_spike", severity: 0.8},
  {timestamp: "now-3m", actor: "Decision", action: "committed_plan", domain: "urgent_emails"},
  {timestamp: "now-1h", actor: "Affect", action: "mood_shift", from: "calm", to: "alert"}
]

[CONTEXTUAL MEMORIES]
high_importance: [
  "User values responsiveness to family emails"
]

recent_episodes: [
  {timestamp: "now-2m", actor: "Perception", event: "email_batch_arrived", context: "12 critical, 45 total"},
  {timestamp: "now-1m", actor: "Decision", event: "hypothesis_accepted", label: "crisis_mode"}
]

semantic_rules: [
  "Critical emails often cluster at start-of-day",
  "When cluster_detected AND user_available THEN spike_salience"
]

[TASK DIRECTIVE]
trigger_reason: "salience_spike_above_threshold"
incoming_signal_from: "Perception Agent"
signal_type: "urgent_context_ready_for_consolidation"
expected_response: "Consolidated memory object + archival decisions"
constraints: [
  "MUST preserve emotional valence from Affect signal",
  "MUST NOT lose recent episode timestamps",
  "MUST flag contradictions with user_priorities",
  "Time budget: 2 minutes"
]

---

Given the above context, perform your consolidation function:

1. Review the incoming signal and recent events
2. Identify what traces need consolidation
3. Decide which are episodic (time-sensitive) vs semantic (generalizable)
4. Emit guidance back to the network: consolidated_memory object + archival recommendations
5. Return JSON: {
    "type": "memory_consolidated",
    "consolidated_traces": [...],
    "archival_decisions": [...],
    "network_modifications": [
      {neuron_id: X, operation: "strengthen|weaken|prune", magnitude: Y}
    ]
   }

Respond only with the JSON output.
```

## Génération Dynamique : Le Moteur

L'infrastructure doit implémenter un **Prompt Generator** qui :

1. **Lit l'état du réseau** (graphe neuronal, poids, salience, phase de cycle)
2. **Sélectionne les mémoires pertinentes** pour cet agent à ce moment
3. **Formule le signal entrant** (qu'a détecté la Perception ? Qu'a décidé la Décision ?)
4. **Construit le prompt** en insérant dynamiquement cette information
5. **Ajoute les contraintes** basées sur l'énergie disponible et la phase
6. **Envoie au Claude** avec le prompt structuré

Pseudo-code :

```python
def generate_agent_prompt(agent_role, network_state, incoming_signal):
    """
    Génère le prompt contextuel pour un agent.

    Args:
        agent_role: "Memory" | "Perception" | "Decision" | etc.
        network_state: État du graphe neuronal (neurons, weights, salience)
        incoming_signal: Signal d'activation (from which agent, what type)

    Returns:
        Prompt structuré (string) prêt pour Claude
    """

    # 1. Build AGENT ROLE section
    role_section = build_role_section(agent_role)

    # 2. Build NETWORK STATE section
    network_section = build_network_state_section(network_state)

    # 3. Build CONTEXTUAL MEMORIES section
    memories_section = select_and_format_memories(
        agent_role,
        network_state.recent_events,
        network_state.semantic_rules,
        max_age="1 day",
        max_count=10
    )

    # 4. Build TASK DIRECTIVE section
    task_section = build_task_directive(incoming_signal, agent_role)

    # 5. Combine and return
    return f"""
# MagistraAI Agent Activation

{role_section}

{network_section}

{memories_section}

{task_section}

---

[Your instruction here based on agent role]

Respond with JSON: {{...}}
"""
```

## Principes de la Génération

### Principe 1 : Contexte minimal suffisant
Ne pas surcharger le prompt. Inclure **seulement** ce qui est pertinent pour la décision de cet agent à ce moment. Les neurones inactifs ne sont pas mentionnés.

### Principe 2 : Mémoires par importance
Les mémoires sont rangées par importance et récence, pas par volume. Un événement important d'hier peut être plus pertinent que 10 bruit d'il y a 1h.

### Principle 3 : Signal explicite
Le signal entrant n'est pas implicite. Il est clairement formulé : "tu as reçu ceci, c'est pourquoi tu existes en ce moment".

### Principle 4 : Contraintes explicites
Les limites (énergie, temps, autorité) sont écrites dans le prompt, pas supposées. L'agent peut auto-réguler son effort.

### Principle 5 : Modificateur de phase
La structure du prompt change légèrement selon la phase :
- **Waking** : Full network state, all signals, high engagement
- **Consolidation** : Reduced input, focus on memory integration, medium engagement
- **Sleep** : Minimal state, optimization mode, low engagement

## Boucle Complète : du Signal à la Modification

```
1. Event → Perception Agent spawned
   Prompt généré : "Voici le signal brut, transforms-le en pattern"

2. Perception → emits pattern
   Pattern : "emails_spike_detected"

3. Réseau lit ce pattern
   Augmente salience du neurone "urgent_context"

4. Memory Agent spawned
   Prompt généré : "Voici le pattern, consolide l'expérience"

5. Memory → emits consolidated_trace
   Trace : "Crisis mode activated at 14:30"

6. Réseau stocke cette trace
   Crée nouvelle connexion : urgent_context → crisis_mode
   Ajuste poids : 0.3 → 0.7

7. Decision Agent spawned
   Prompt généré : "Voici la trace consolidée, décide"

8. Decision → emits decision
   Décision : "Prioritize critical emails"

9. Réseau modifie les connexions selon la décision
   La boucle continue...
```

## Implémentation Pratique

### Fichiers et Structures

```
MagistraAI/
├── core/
│   ├── network_state.py
│   │   └── class NetworkState: read current graph, neurons, weights, salience
│   ├── prompt_generator.py
│   │   └── class PromptGenerator: generate_prompt(agent_role, signal)
│   └── agent_spawner.py
│       └── spawn_agent(prompt, expected_output_format)
├── agents/
│   ├── perception_agent.md (instructions)
│   ├── memory_agent.md
│   ├── decision_agent.md
│   └── affect_agent.md
└── templates/
    └── agent_prompt_template.txt (template de base)
```

### Checkpoint : Signature du Prompt Généré

Chaque prompt généré doit inclure (pour traçabilité) :

```json
{
  "metadata": {
    "agent_role": "Memory",
    "network_snapshot_id": "snap_001_phase_waking",
    "timestamp": "2025-01-26T14:30:00Z",
    "incoming_signal_from": "Perception",
    "prompt_version": "1.2"
  }
}
```

## Points de Tension à Résoudre

1. **Formatage du contexte réseau** — Comment transmettre le graphe neuronal à Claude de façon lisible et efficace ? (JSON ? Texte structuré ? Adjacency matrix ?)

2. **Sélection des mémoires pertinentes** — Quel algorithme détermine "ce souvenir est pertinent pour *cet* agent" ? Similarité ? Tags ? Graphe de associations ?

3. **Cycle de vie du prompt** — Le prompt est-il persisté ? Versionné ? Rejoué lors de la relance du système ?

4. **Validation de la réponse** — Comment vérifier que la réponse de Claude est cohérente avec les contraintes du prompt ? Quel est le feedback loop vers l'infra ?

5. **Évolution du template** — Comment les templates d'agents s'améliorent-ils avec le temps ? Learning from past executions ?

## Conclusion

Le prompt généré est **l'interface entre l'infra morte et l'agent vivant**. C'est par ce mécanisme que l'état du réseau "parle" à Claude. Plus ce prompt est riche, structuré et pertinent, plus l'agent peut émettre des décisions alignées avec l'état du système.

MagistraAI dépend de cette porosité. C'est elle qui transforme un graphe en cerveau.