Spaces:
Running
Running
| # 🎭 Animetix: Complete Technical & Functional Reference Guide | |
| This document serves as the comprehensive technical specification and operations manual for the **Animetix** platform (Anime Archetype Engine). It is designed for AI engineers, fullstack developers, and system architects maintaining or extending this cognitive ecosystem. | |
| --- | |
| ## 🏛️ 1. Cognitive Architecture: Hexagon 2.0 | |
| Animetix is built around an **Atomic & Hexagonal Architecture** (Ports & Adapters), separating pure business workflows from underlying frameworks. | |
| ### A. Core Domain (Pure Intelligence) | |
| The domain layer (`backend/core/domain/`) encapsulates the application's core intelligence: | |
| - **Services (e.g., `AgenticRAGService`):** Orchestrate multi-step cognitive agents. | |
| - **InferencePort:** Interface boundary supporting Server-Sent Events (SSE) streaming, Test-Time Compute (TTC) routing, and `rerank_documents` Cross-Encoder operations. | |
| - **PersistencePort (UnifiedRepository):** Defines unified data read/write rules, delegating to vector search indices and Neo4j relational structures. | |
| ### B. Infrastructure (Adapters) | |
| - **Persistence:** Concrete adapters implementing database interfaces (Vertex AI, pgvector, Neo4j, Django DB). | |
| - **Inference:** Implementations for cloud services (Google GenAI, BrainAPI) and local endpoints (Ollama, local Transformers). Uses lazy imports to prevent overhead at startup. | |
| --- | |
| ## 🧠 2. Deep Dive: AI Pipelines & Models | |
| ### A. Inference & Reasoning Cascade (LLM & SLM) | |
| Animetix employs a cascade of models to optimize the **Cost / Latency / Accuracy** ratio: | |
| 1. **Thinking Model (8B+ - e.g., DeepSeek-R1 Distill):** Triggered only when the Complexity Analyzer detects highly ambiguous queries. It generates internal logical thought steps (`<thought>`) before outputting text. | |
| 2. **Synthesis Model (8B - e.g., Llama-3 / Qwen-3):** The standard model for high-quality conversational output. | |
| 3. **Scout & Critic (1B-3B - e.g., Phi-4-mini / SmolLM3):** Ultra-lightweight models running on CPU/entry-level GPU for structural sub-second tasks (entity extraction, safety audits, rating). | |
| 4. **BitNet Quantization (1.58-bit):** Employs ternary weights to run models with up to 70% VRAM savings. | |
| ### B. Matryoshka Representation Learning (MRL) | |
| Animetix implements MRL on top of the **Jina-v3** embedding model: | |
| - **Concept:** Embedding vectors are trained to pack the most critical semantic information into the early dimensions. | |
| - **Query Flow:** | |
| 1. **Short-List Phase:** Vector similarity search is executed on the first **128 dimensions** (using an HNSW index). This is up to 8x faster than loading the entire vector. | |
| 2. **Zoom Phase:** The top 50 matches are re-evaluated using the full **1024 dimensions** for precise ranking. | |
| - **Result:** Semantic search latency is kept below `50ms` on large catalogs. | |
| ### C. Multimodal & Audio Pipelines | |
| 1. **Vision Encoder (SigLIP-SO400M):** SigLIP aligns image-text features using a sigmoid loss function, enabling finer image description parsing than traditional CLIP. | |
| 2. **Visual Reranker (Qwen-VL):** For complex visual queries, a Vision-Language Model inspects image files directly to confirm similarity. | |
| 3. **Voice Cloning (RVC):** The `VoiceCloningService` clones character voices from a 10-second reference audio sample (zero-shot) for voice synthesizer playback. | |
| 4. **Gemini Multimodal Live API:** Relays PCM audio bidirectionally over WebSockets, bypassing text transcription for low-latency voice-to-voice companion dialogues. | |
| --- | |
| ## 🕸️ 3. Knowledge Graph & GraphRAG | |
| ### A. Neo4j Ontology | |
| The graph database maps structural relationships: | |
| - **Nodes:** `Media`, `Studio`, `Creator`, `Character`, `MicroTag` (granular themes). | |
| - **Edges:** `PRODUCED_BY`, `CREATED_BY`, `FEATURES`, `HAS_THEME`, `INFLUENCED_BY`. | |
| ### B. Graph Algorithms | |
| - **Multi-Hop Traversal:** The agent can navigate relationships (e.g., *"Find anime produced by the studio that made 'Arcane' but with an art style resembling 'Spirited Away'"*) by traversing graph nodes before performing vector similarity matches. | |
| - **Leiden Community Summarization:** Runs community detection (Leiden algorithm) on Neo4j to summarize global knowledge clusters (e.g., "History of Cyberpunk in the 90s"). | |
| --- | |
| ## 🎮 4. Game Modes In-Depth | |
| ### 1. Paradox Quest (Neuro-Symbolic Logic) | |
| * **Engine:** Fuses LLMs with a formal logic solver (Z3). | |
| * **Workflow:** | |
| 1. **Fact Extraction:** The LLM extracts narrative properties of titles as Boolean states. | |
| 2. **SAT Solver:** The **Z3 Solver** processes these predicates to mathematically prove which item is the intruder. | |
| 3. **Narrative Rendering:** The LLM translates the logical contradiction into a riddle. | |
| ### 2. Akinetix RL (Reinforcement Learning) | |
| * **Engine:** Proximal Policy Optimization (PPO). | |
| * **Workflow:** The agent has been trained in a simulated Gym environment (`AkinetixRLService`) to select questions that maximize information gain (entropy), guessing the player's character in minimal turns. | |
| ### 3. La Forge (Multimedia Generation) | |
| * **Engine:** Stable Diffusion XL + IP-Adapter + ControlNet. | |
| * **Workflow:** Fuses two creative IPs. The LLM generates a hybrid synopsis, while the diffusion pipeline generates posters preserving character features and postures. | |
| ### 4. Spatial Computing (3D Reconstruction) | |
| * **Engine:** DepthAnything + Three.js renderer. | |
| * **Workflow:** Estimates depth maps from 2D posters and generates a 3D volumetric scene, rendering a navigable diorama in the browser. | |
| --- | |
| ## 📊 5. MLOps, Security & Observability | |
| ### A. Real-Time Critic (Ragas) | |
| Animetix employs an **LLM-as-a-Judge** evaluation loop: | |
| - Every generation is audited on Ragas metrics (Faithfulness, Relevancy). | |
| - If Faithfulness falls below `0.7`, a safety disclaimer is attached, or the response is rewritten. | |
| ### B. DPO Pipeline (Direct Preference Optimization) | |
| - **Ingestion:** User upvotes/downvotes and corrections are captured. | |
| - **Feedback Loop:** Malformed generations are formatted into `(Prompt, Chosen, Rejected)` JSONL datasets. | |
| - **Alignment:** Datasets are used for continuous LoRA training. | |
| ### C. Explainable AI (XAI) & Latent Space Projection | |
| - **Token logprobs & Uncertainty**: Inspects token-level logprobabilities and cumulative entropy directly during streaming generation to measure confidence and flag hallucination risks. | |
| - **Attention Heatmaps & Logit Lens**: Collects attention matrices and projects intermediate representation vectors onto the vocabulary space (logit lens) to visualize which layers formulate specific reasoning concepts. | |
| - **Neural Diagnostics**: Exposes an interactive visualizer mapping the user's current query alongside catalog embeddings inside a projected 3D semantic space. | |
| ### D. Embeddings & Archetype Drift Detection | |
| - **Baselines & Distributions**: Scheduled batch jobs calculate Wasserstein distance / semantic drift of recent user query embeddings against baseline distributions (`generate_drift_baselines`). | |
| - **Alerting**: Automatically triggers alerts and recalibrates user semantic weights if an archetype collapse (e.g., preference saturation or drift) is detected. | |
| --- | |
| ## 🛡️ 6. Safety, Compliance & Billing Automation | |
| - **Prompt Sanitization**: Ingested context is audited to block indirect prompt injections. | |
| - **Token DoS Protection**: Rate limiting and payload size gates protect endpoints. | |
| - **OpenTelemetry Tracing**: Spans are enriched with semantic agentic attributes and exported directly to Cloud Trace. | |
| - **Secure Billing Budget Caps**: Relies on a secure Pub/Sub Push Subscription OIDC webhook (`/api/billing/webhook/`) that listens to GCP billing budget alerts. | |
| - **Graceful Degradation**: When a budget cap is reached (e.g., $100 monthly budget exceeded), the webhook automatically updates the active service state, executing a graceful shutdown of heavy GPU ML inference services (the Brain API) and falling back to light SLMs/local CPUs to guarantee 0% cost overrun. | |
| --- | |
| ## 🚀 7. Deployment Lifecycle | |
| 1. **Declarative Manifest**: Define environment variables, scaling thresholds, WAF rules, and Secrets references in [deployments.yaml](file:///c:/Users/bahma/PycharmProjects/Projet%20solo/Double_scenario_Project/deploy/deployments.yaml). | |
| 2. **Staging**: Deploy using Docker Stack (Postgres, Redis, Neo4j, Ollama). | |
| 3. **Pre-Flight**: Execute `python backend/api/manage.py check_db_status` and `python scripts/verify/pre_flight_check.py` to validate environment bindings. | |
| 4. **Production**: Enable Daphne ASGI server for SSE streaming and WebSockets. | |
| --- | |
| *End of Technical Document - Animetix - July 2026* | |