refactor(graph): remove hardcoded ZEP checks, use get_graph_config_errors; add embed/small LLM env docs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

azure/config.sh.example

@@ -56,6 +56,19 @@ ZEP_API_KEY="<la-teva-zep-api-key>"
 # NEO4J_URI="bolt://<ip-o-hostname>:7687"
 # NEO4J_USER="neo4j"
 # NEO4J_PASSWORD="<contrasenya-neo4j>"
+# GRAPHITI_BATCH_SIZE="10"  # chunks per crida bulk; més alt = més ràpid però més paral·lelisme LLM
+
+# --- Embedding LLM (usat per Graphiti per a indexació vectorial) ---
+# Si no s'estableix, fa fallback a LLM_API_KEY / LLM_BASE_URL.
+# LLM_EMBED_API_KEY="<la-teva-embed-api-key>"
+# LLM_EMBED_BASE_URL="https://<recurs>.cognitiveservices.azure.com/openai/deployments/<embed-deployment>/embeddings?api-version=2024-05-01-preview"
+# LLM_EMBED_MODEL_NAME="text-embedding-3-small"
+
+# --- Small/fast LLM (usat per Graphiti per a reranking i tasques lleugeres) ---
+# Si no s'estableix, fa fallback a LLM_API_KEY / LLM_BASE_URL / LLM_MODEL_NAME.
+# LLM_SMALL_API_KEY="<la-teva-small-api-key>"
+# LLM_SMALL_BASE_URL="https://<recurs>.cognitiveservices.azure.com/openai/deployments/<small-model>/chat/completions?api-version=2024-05-01-preview"
+# LLM_SMALL_MODEL_NAME="gpt-4o-mini"
 
 # ── Simulació OASIS (valors per defecte recomanats) ───────────────────────────
 OASIS_DEFAULT_MAX_ROUNDS="10"

backend/app/api/graph.py

@@ -284,9 +284,7 @@ def build_graph():
         logger.info("=== Starting graph build ===")
 
         # Check configuration
-        errors = []
+        errors = Config.get_graph_config_errors()
-        if not Config.ZEP_API_KEY:
-            errors.append(t('api.zepApiKeyMissing'))
         if errors:
             logger.error(f"Configuration error: {errors}")
             return jsonify({
@@ -387,7 +385,7 @@ def build_graph():
                 )
                 
                 # Create graph builder service
-                builder = GraphBuilderService(api_key=Config.ZEP_API_KEY)
+                builder = GraphBuilderService()
 
                 # Split into chunks
                 task_manager.update_task(
@@ -437,10 +435,11 @@ def build_graph():
                     progress=15
                 )
                 
+                batch_size = Config.GRAPHITI_BATCH_SIZE if Config.GRAPH_BACKEND == 'graphiti' else 3
                 episode_uuids = builder.add_text_batches(
-                    graph_id, 
+                    graph_id,
                     chunks,
-                    batch_size=3,
+                    batch_size=batch_size,
                     progress_callback=add_progress_callback
                 )
                 
@@ -572,13 +571,7 @@ def get_graph_data(graph_id: str):
     Get graph data (nodes and edges)
     """
     try:
-        if not Config.ZEP_API_KEY:
+        builder = GraphBuilderService()
-            return jsonify({
-                "success": False,
-                "error": t('api.zepApiKeyMissing')
-            }), 500
-        
-        builder = GraphBuilderService(api_key=Config.ZEP_API_KEY)
         graph_data = builder.get_graph_data(graph_id)
         
         return jsonify({
@@ -600,13 +593,7 @@ def delete_graph(graph_id: str):
     Delete a Zep graph
     """
     try:
-        if not Config.ZEP_API_KEY:
+        builder = GraphBuilderService()
-            return jsonify({
-                "success": False,
-                "error": t('api.zepApiKeyMissing')
-            }), 500
-        
-        builder = GraphBuilderService(api_key=Config.ZEP_API_KEY)
         builder.delete_graph(graph_id)
         
         return jsonify({

backend/app/api/simulation.py

@@ -57,12 +57,6 @@ def get_graph_entities(graph_id: str):
         enrich: whether to fetch related edge info (default true)
     """
     try:
-        if not Config.ZEP_API_KEY:
-            return jsonify({
-                "success": False,
-                "error": t('api.zepApiKeyMissing')
-            }), 500
-        
         entity_types_str = request.args.get('entity_types', '')
         entity_types = [t.strip() for t in entity_types_str.split(',') if t.strip()] if entity_types_str else None
         enrich = request.args.get('enrich', 'true').lower() == 'true'
@@ -94,12 +88,6 @@ def get_graph_entities(graph_id: str):
 def get_entity_detail(graph_id: str, entity_uuid: str):
     """Get detailed information about a single entity"""
     try:
-        if not Config.ZEP_API_KEY:
-            return jsonify({
-                "success": False,
-                "error": t('api.zepApiKeyMissing')
-            }), 500
-        
         reader = ZepEntityReader()
         entity = reader.get_entity_with_context(graph_id, entity_uuid)
         
@@ -127,12 +115,6 @@ def get_entity_detail(graph_id: str, entity_uuid: str):
 def get_entities_by_type(graph_id: str, entity_type: str):
     """Get all entities of a specified type"""
     try:
-        if not Config.ZEP_API_KEY:
-            return jsonify({
-                "success": False,
-                "error": t('api.zepApiKeyMissing')
-            }), 500
-        
         enrich = request.args.get('enrich', 'true').lower() == 'true'
         
         reader = ZepEntityReader()