feat(ai): configurable max_tokens for extraction via init and database

- Add --max-tokens flag to configure.py ai-provider
- Store max_tokens in ai_extraction_config table (column already existed)
- OpenRouterProvider reads max_tokens from config (default 16384)
- Init flow prompts for max tokens with press-enter-to-accept default
- Factory passes max_tokens from database config to provider

Author: aaronsb

api/app/lib/ai_providers.py

@@ -973,6 +973,7 @@ def __init__(
         api_key: Optional[str] = None,
         extraction_model: Optional[str] = None,
         embedding_provider: Optional[AIProvider] = None,
+        max_tokens: Optional[int] = None,
     ):
         """
         Initialize OpenRouter provider.
@@ -982,6 +983,7 @@ def __init__(
             extraction_model: Model ID (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4')
             embedding_provider: Separate provider for embeddings (required — OpenRouter
                                doesn't serve embeddings)
+            max_tokens: Max completion tokens for extraction (default: 16384)
         """
         from openai import OpenAI
 
@@ -1012,6 +1014,7 @@ def __init__(
         self.extraction_model = extraction_model or os.getenv(
             "OPENROUTER_EXTRACTION_MODEL", "openai/gpt-4o"
         )
+        self.max_tokens = max_tokens or 16384
         self.embedding_provider = embedding_provider
 
     def extract_concepts(
@@ -1028,7 +1031,7 @@ def extract_concepts(
                     {"role": "system", "content": system_prompt},
                     {"role": "user", "content": f"Text to analyze:\n\n{text}"},
                 ],
-                max_tokens=16384,
+                max_tokens=self.max_tokens,
                 temperature=0.3,
                 response_format={"type": "json_object"},
             )
@@ -1836,11 +1839,14 @@ def get_provider(provider_name: Optional[str] = None) -> AIProvider:
 
     # Determine provider and model based on DEVELOPMENT_MODE
     extraction_model = None
+    max_tokens = None
 
     if is_development_mode():
         # Development mode: Use environment variables
         provider_name = provider_name or os.getenv("AI_PROVIDER", "openai").lower()
-        # extraction_model will be set by provider constructor from env vars
+        max_tokens_env = os.getenv("MAX_EXTRACTION_TOKENS")
+        if max_tokens_env:
+            max_tokens = int(max_tokens_env)
         logger.debug(f"[DEV MODE] Using .env configuration: provider={provider_name}")
     else:
         # Production mode: Load from database
@@ -1859,7 +1865,8 @@ def get_provider(provider_name: Optional[str] = None) -> AIProvider:
 
         provider_name = provider_name or config['provider']
         extraction_model = config['model_name']
-        logger.debug(f"[PROD MODE] Using database configuration: provider={provider_name}, model={extraction_model}")
+        max_tokens = config.get('max_tokens')
+        logger.debug(f"[PROD MODE] Using database configuration: provider={provider_name}, model={extraction_model}, max_tokens={max_tokens}")
 
     # Check for separate embedding provider configuration
     embedding_provider = get_embedding_provider()
@@ -1902,6 +1909,7 @@ def get_provider(provider_name: Optional[str] = None) -> AIProvider:
         return OpenRouterProvider(
             extraction_model=extraction_model,
             embedding_provider=embedding_provider,
+            max_tokens=max_tokens,
         )
     elif provider_name == "mock":
         from .mock_ai_provider import MockAIProvider

operator/configure.py

@@ -114,6 +114,7 @@ def cmd_ai_provider(self, args):
         """Configure AI extraction provider"""
         provider = args.provider
         model = args.model
+        max_tokens = getattr(args, 'max_tokens', None)
 
         if not provider:
             print("❌ Provider required (openai, anthropic, ollama, or openrouter)")
@@ -161,14 +162,15 @@ def cmd_ai_provider(self, args):
                 # Insert/update configuration
                 cur.execute(
                     """INSERT INTO kg_api.ai_extraction_config
-                       (provider, model_name, supports_vision, supports_json_mode, active)
-                       VALUES (%s, %s, true, true, true)
+                       (provider, model_name, supports_vision, supports_json_mode, max_tokens, active)
+                       VALUES (%s, %s, true, true, %s, true)
                        ON CONFLICT (active) WHERE active = true
                        DO UPDATE SET
                          provider = EXCLUDED.provider,
                          model_name = EXCLUDED.model_name,
+                         max_tokens = COALESCE(EXCLUDED.max_tokens, kg_api.ai_extraction_config.max_tokens),
                          updated_at = NOW()""",
-                    (provider, model)
+                    (provider, model, max_tokens)
                 )
                 conn.commit()
                 print(f"✅ Configured AI extraction: {provider} / {model}")
@@ -653,6 +655,7 @@ def main():
     ai_parser = subparsers.add_parser('ai-provider', help='Configure AI extraction provider')
     ai_parser.add_argument('provider', nargs='?', help='Provider: openai, anthropic, ollama, openrouter')
     ai_parser.add_argument('--model', help='Model name (optional, uses default)')
+    ai_parser.add_argument('--max-tokens', type=int, help='Max completion tokens for extraction (default: 16384)')
 
     # embedding
     embed_parser = subparsers.add_parser('embedding', help='List or activate embedding profile')

operator/lib/guided-init.sh

@@ -547,12 +547,18 @@ else
             echo ""
             echo -e "${GREEN}→${NC} Selected: ${BOLD}${CHOSEN_NAME}${NC} (${CHOSEN_MODEL_ID})"
 
+            # Prompt for max completion tokens with sensible default
+            echo ""
+            read -p "Max completion tokens [16384]: " -r MAX_TOKENS_INPUT
+            MAX_TOKENS="${MAX_TOKENS_INPUT:-16384}"
+            echo -e "${GREEN}→${NC} Max tokens: ${MAX_TOKENS}"
+
             # Enable and set as default in catalog
             docker exec kg-operator python /workspace/operator/configure.py models enable "$CHOSEN_CATALOG_ID" 2>/dev/null
             docker exec kg-operator python /workspace/operator/configure.py models default "$CHOSEN_CATALOG_ID" 2>/dev/null
 
-            # Update active extraction config with chosen model
-            docker exec kg-operator python /workspace/operator/configure.py ai-provider "$AI_PROVIDER" --model "$CHOSEN_MODEL_ID"
+            # Update active extraction config with chosen model and max tokens
+            docker exec kg-operator python /workspace/operator/configure.py ai-provider "$AI_PROVIDER" --model "$CHOSEN_MODEL_ID" --max-tokens "$MAX_TOKENS"
             SELECTING=false
         else
             echo -e "${YELLOW}→${NC} Invalid choice, please try again."