abstractcore 2.6.9__tar.gz → 2.9.1__tar.gz

{abstractcore-2.6.9 → abstractcore-2.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractcore
-Version: 2.6.9
+Version: 2.9.1
 Summary: Unified interface to all LLM providers with essential infrastructure for tool calling, streaming, and model management
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 Maintainer-email: Laurent-Philippe Albou <contact@abstractcore.ai>
@@ -30,6 +30,7 @@ Requires-Dist: pydantic<3.0.0,>=2.0.0
 Requires-Dist: httpx<1.0.0,>=0.24.0
 Requires-Dist: tiktoken<1.0.0,>=0.5.0
 Requires-Dist: requests<3.0.0,>=2.25.0
+Requires-Dist: beautifulsoup4<5.0.0,>=4.12.0
 Requires-Dist: Pillow<12.0.0,>=10.0.0
 Provides-Extra: openai
 Requires-Dist: openai<2.0.0,>=1.0.0; extra == "openai"
@@ -57,8 +58,15 @@ Provides-Extra: processing
 Provides-Extra: tools
 Requires-Dist: beautifulsoup4<5.0.0,>=4.12.0; extra == "tools"
 Requires-Dist: lxml<6.0.0,>=4.9.0; extra == "tools"
-Requires-Dist: duckduckgo-search<4.0.0,>=3.8.0; extra == "tools"
+Requires-Dist: ddgs<10.0.0,>=9.10.0; python_version >= "3.10" and extra == "tools"
+Requires-Dist: duckduckgo-search<4.0.0,>=3.8.0; python_version < "3.10" and extra == "tools"
 Requires-Dist: psutil<6.0.0,>=5.9.0; extra == "tools"
+Provides-Extra: tool
+Requires-Dist: beautifulsoup4<5.0.0,>=4.12.0; extra == "tool"
+Requires-Dist: lxml<6.0.0,>=4.9.0; extra == "tool"
+Requires-Dist: ddgs<10.0.0,>=9.10.0; python_version >= "3.10" and extra == "tool"
+Requires-Dist: duckduckgo-search<4.0.0,>=3.8.0; python_version < "3.10" and extra == "tool"
+Requires-Dist: psutil<6.0.0,>=5.9.0; extra == "tool"
 Provides-Extra: media
 Requires-Dist: Pillow<12.0.0,>=10.0.0; extra == "media"
 Requires-Dist: pymupdf4llm<1.0.0,>=0.0.20; extra == "media"
@@ -195,6 +203,50 @@ response = llm.generate(
 print(response.content)
 ```
 
+### Tool Execution Modes
+
+AbstractCore supports two tool execution modes:
+
+**Mode 1: Passthrough (Default)** - Returns raw tool call tags for downstream processing
+
+```python
+from abstractcore import create_llm
+from abstractcore.tools import tool
+
+@tool(name="get_weather", description="Get weather for a city")
+def get_weather(city: str) -> str:
+    return f"Weather in {city}: Sunny, 22°C"
+
+llm = create_llm("ollama", model="qwen3:4b")  # execute_tools=False by default
+response = llm.generate("What's the weather in Paris?", tools=[get_weather])
+# response.content contains raw tool call tags: <|tool_call|>...
+# Downstream runtime (AbstractRuntime, Codex, Claude Code) parses and executes
+```
+
+**Use case**: Agent loops, AbstractRuntime, Codex, Claude Code, custom orchestration
+
+**Mode 2: Direct Execution** - AbstractCore executes tools and returns results
+
+```python
+from abstractcore import create_llm
+from abstractcore.tools import tool
+from abstractcore.tools.registry import register_tool
+
+@tool(name="get_weather", description="Get weather for a city")
+def get_weather(city: str) -> str:
+    return f"Weather in {city}: Sunny, 22°C"
+
+register_tool(get_weather)  # Required for direct execution
+
+llm = create_llm("ollama", model="qwen3:4b", execute_tools=True)
+response = llm.generate("What's the weather in Paris?", tools=[get_weather])
+# response.content contains executed tool results
+```
+
+**Use case**: Simple scripts, single-turn tool use
+
+> **Note**: The `@tool` decorator creates metadata but does NOT register globally. Tools are passed explicitly to `generate()`. Use `register_tool()` only when using direct execution mode.
+
 ### Response Object (GenerateResponse)
 
 Every LLM generation returns a **GenerateResponse** object with consistent structure across all providers:
@@ -238,6 +290,8 @@ print(f"Summary: {response.get_summary()}")         # "Model: gpt-4o-mini | Toke
 
 AbstractCore includes a comprehensive set of ready-to-use tools for common tasks:
 
+> Note: `abstractcore.tools.common_tools` requires `abstractcore[tools]` (BeautifulSoup, lxml, web search backends, etc.).
+
 ```python
 from abstractcore.tools.common_tools import fetch_url, search_files, read_file
 

{abstractcore-2.6.9 → abstractcore-2.9.1}/README.md

@@ -65,6 +65,50 @@ response = llm.generate(
 print(response.content)
 ```
 
+### Tool Execution Modes
+
+AbstractCore supports two tool execution modes:
+
+**Mode 1: Passthrough (Default)** - Returns raw tool call tags for downstream processing
+
+```python
+from abstractcore import create_llm
+from abstractcore.tools import tool
+
+@tool(name="get_weather", description="Get weather for a city")
+def get_weather(city: str) -> str:
+    return f"Weather in {city}: Sunny, 22°C"
+
+llm = create_llm("ollama", model="qwen3:4b")  # execute_tools=False by default
+response = llm.generate("What's the weather in Paris?", tools=[get_weather])
+# response.content contains raw tool call tags: <|tool_call|>...
+# Downstream runtime (AbstractRuntime, Codex, Claude Code) parses and executes
+```
+
+**Use case**: Agent loops, AbstractRuntime, Codex, Claude Code, custom orchestration
+
+**Mode 2: Direct Execution** - AbstractCore executes tools and returns results
+
+```python
+from abstractcore import create_llm
+from abstractcore.tools import tool
+from abstractcore.tools.registry import register_tool
+
+@tool(name="get_weather", description="Get weather for a city")
+def get_weather(city: str) -> str:
+    return f"Weather in {city}: Sunny, 22°C"
+
+register_tool(get_weather)  # Required for direct execution
+
+llm = create_llm("ollama", model="qwen3:4b", execute_tools=True)
+response = llm.generate("What's the weather in Paris?", tools=[get_weather])
+# response.content contains executed tool results
+```
+
+**Use case**: Simple scripts, single-turn tool use
+
+> **Note**: The `@tool` decorator creates metadata but does NOT register globally. Tools are passed explicitly to `generate()`. Use `register_tool()` only when using direct execution mode.
+
 ### Response Object (GenerateResponse)
 
 Every LLM generation returns a **GenerateResponse** object with consistent structure across all providers:
@@ -108,6 +152,8 @@ print(f"Summary: {response.get_summary()}")         # "Model: gpt-4o-mini | Toke
 
 AbstractCore includes a comprehensive set of ready-to-use tools for common tasks:
 
+> Note: `abstractcore.tools.common_tools` requires `abstractcore[tools]` (BeautifulSoup, lxml, web search backends, etc.).
+
 ```python
 from abstractcore.tools.common_tools import fetch_url, search_files, read_file
 

{abstractcore-2.6.9 → abstractcore-2.9.1}/abstractcore/apps/summarizer.py

@@ -6,23 +6,39 @@ Usage:
     python -m abstractcore.apps.summarizer <file_path> [options]
 
 Options:
-    --style <style>         Summary style (structured, narrative, objective, analytical, executive, conversational)
-    --length <length>       Summary length (brief, standard, detailed, comprehensive)
-    --focus <focus>         Specific focus area for summarization
-    --output <output>       Output file path (optional, prints to console if not provided)
-    --chunk-size <size>     Chunk size in characters (default: 8000, max: 32000)
-    --provider <provider>   LLM provider (requires --model)
-    --model <model>         LLM model (requires --provider)
-    --max-tokens <tokens>   Maximum total tokens for LLM context (default: 32000)
-    --max-output-tokens <tokens> Maximum tokens for LLM output generation (default: 8000)
-    --verbose              Show detailed progress information
-    --help                 Show this help message
+    --style <style>              Summary style (structured, narrative, objective, analytical, executive, conversational)
+    --length <length>            Summary length (brief, standard, detailed, comprehensive)
+    --focus <focus>              Specific focus area for summarization
+    --output <output>            Output file path (optional, prints to console if not provided)
+    --chunk-size <size>          Chunk size in characters (default: 8000, max: 32000)
+    --provider <provider>        LLM provider (requires --model)
+    --model <model>              LLM model (requires --provider)
+    --max-tokens <tokens|auto>   Maximum total tokens for LLM context (default: auto)
+                                 - 'auto' or -1: Uses model's full context window
+                                 - Specific number: Hard limit for deployment constraint (GPU/RAM)
+    --max-output-tokens <tokens|auto> Maximum tokens for LLM output (default: auto)
+    --verbose                    Show detailed progress information
+    --help                       Show this help message
+
+Memory Management:
+    --max-tokens controls token budget:
+    - Use 'auto' (default): Automatically uses model's full capability
+    - Use specific value: Hard limit for memory-constrained environments (e.g., --max-tokens 16000)
+    
+    Example: 8GB GPU → --max-tokens 16000, 16GB GPU → --max-tokens 32000
 
 Examples:
+    # Auto mode (uses model's full capability)
     python -m abstractcore.apps.summarizer document.pdf
-    python -m abstractcore.apps.summarizer report.txt --style executive --length brief --verbose
-    python -m abstractcore.apps.summarizer data.md --focus "technical details" --output summary.txt
-    python -m abstractcore.apps.summarizer large.txt --chunk-size 15000 --provider openai --model gpt-4o-mini
+    
+    # Memory-constrained (8GB GPU)
+    python -m abstractcore.apps.summarizer report.txt --max-tokens 16000
+    
+    # Large document with specific style
+    python -m abstractcore.apps.summarizer data.md --style executive --length brief
+    
+    # Custom model with hard limit
+    python -m abstractcore.apps.summarizer large.txt --provider openai --model gpt-4o-mini --max-tokens 24000
 """
 
 import argparse
@@ -239,16 +255,14 @@ Default model setup:
 
     parser.add_argument(
         '--max-tokens',
-        type=int,
-        default=32000,
-        help='Maximum total tokens for LLM context (default: 32000)'
+        default='auto',
+        help='Maximum total tokens for LLM context (default: auto). Use "auto" or -1 for model\'s full capability, or specific number for hard limit (e.g., 16000 for 8GB GPU)'
     )
 
     parser.add_argument(
         '--max-output-tokens',
-        type=int,
-        default=8000,
-        help='Maximum tokens for LLM output generation (default: 8000)'
+        default='auto',
+        help='Maximum tokens for LLM output generation (default: auto). Use "auto" or -1 for model\'s capability, or specific number'
     )
 
     parser.add_argument(
@@ -329,19 +343,40 @@ Default model setup:
             provider, model = get_app_defaults('summarizer')
             config_source = "configured defaults"
 
-        # Adjust max_tokens based on chunk size
-        max_tokens = max(args.max_tokens, args.chunk_size)
+        # Parse max_tokens (support 'auto', -1, or specific number)
+        if args.max_tokens in ('auto', 'Auto', 'AUTO'):
+            max_tokens = -1
+        else:
+            try:
+                max_tokens = int(args.max_tokens)
+            except ValueError:
+                print(f"Error: --max-tokens must be 'auto' or a number, got: {args.max_tokens}")
+                sys.exit(1)
+        
+        # Parse max_output_tokens (support 'auto', -1, or specific number)
+        if args.max_output_tokens in ('auto', 'Auto', 'AUTO'):
+            max_output_tokens = -1
+        else:
+            try:
+                max_output_tokens = int(args.max_output_tokens)
+            except ValueError:
+                print(f"Error: --max-output-tokens must be 'auto' or a number, got: {args.max_output_tokens}")
+                sys.exit(1)
 
         if args.verbose:
-            print(f"Initializing summarizer ({provider}, {model}, {max_tokens} token context, {args.max_output_tokens} output tokens) - using {config_source}...")
+            max_tokens_display = "AUTO" if max_tokens == -1 else str(max_tokens)
+            max_output_display = "AUTO" if max_output_tokens == -1 else str(max_output_tokens)
+            print(f"Initializing summarizer ({provider}, {model}, {max_tokens_display} token context, {max_output_display} output tokens) - using {config_source}...")
 
         if args.debug:
+            max_tokens_display = "AUTO" if max_tokens == -1 else str(max_tokens)
+            max_output_display = "AUTO" if max_output_tokens == -1 else str(max_output_tokens)
             print(f"🐛 Debug - Configuration details:")
             print(f"   Provider: {provider}")
             print(f"   Model: {model}")
             print(f"   Config source: {config_source}")
-            print(f"   Max tokens: {max_tokens}")
-            print(f"   Max output tokens: {args.max_output_tokens}")
+            print(f"   Max tokens: {max_tokens_display}")
+            print(f"   Max output tokens: {max_output_display}")
             print(f"   Chunk size: {args.chunk_size}")
             print(f"   Timeout: {args.timeout}")
             print(f"   Style: {args.style}")
@@ -349,12 +384,19 @@ Default model setup:
             print(f"   Focus: {args.focus}")
 
         try:
-            llm = create_llm(provider, model=model, max_tokens=max_tokens, max_output_tokens=args.max_output_tokens, timeout=args.timeout)
+            # When using auto mode (-1), don't pass to create_llm (let provider use defaults)
+            llm_kwargs = {'timeout': args.timeout}
+            if max_tokens != -1:
+                llm_kwargs['max_tokens'] = max_tokens
+            if max_output_tokens != -1:
+                llm_kwargs['max_output_tokens'] = max_output_tokens
+            
+            llm = create_llm(provider, model=model, **llm_kwargs)
             summarizer = BasicSummarizer(
                 llm,
                 max_chunk_size=args.chunk_size,
                 max_tokens=max_tokens,
-                max_output_tokens=args.max_output_tokens,
+                max_output_tokens=max_output_tokens,
                 timeout=args.timeout
             )
         except Exception as e:

{abstractcore-2.6.9 → abstractcore-2.9.1}/abstractcore/architectures/detection.py

@@ -20,6 +20,41 @@ _model_capabilities: Optional[Dict[str, Any]] = None
 # Cache for resolved model names and architectures to reduce redundant logging
 _resolved_aliases_cache: Dict[str, str] = {}
 _detected_architectures_cache: Dict[str, str] = {}
+# Cache to avoid repeating default-capabilities warnings for the same unknown model.
+_default_capabilities_warning_cache: set[str] = set()
+
+
+# Some callers pass provider/model as a single string (e.g. "lmstudio/qwen/qwen3-next-80b").
+# For capability lookup we want the underlying model id, not the provider prefix.
+_KNOWN_PROVIDER_PREFIXES = {
+    "anthropic",
+    "azure",
+    "bedrock",
+    "fireworks",
+    "gemini",
+    "google",
+    "groq",
+    "huggingface",
+    "lmstudio",
+    "local",
+    "mlx",
+    "nvidia",
+    "ollama",
+    "openai",
+    "openai-compatible",
+    "together",
+    "vllm",
+}
+
+
+def _strip_provider_prefix(model_name: str) -> str:
+    s = str(model_name or "").strip()
+    if not s or "/" not in s:
+        return s
+    head, rest = s.split("/", 1)
+    if head.strip().lower() in _KNOWN_PROVIDER_PREFIXES and rest.strip():
+        return rest.strip()
+    return s
 
 
 def _load_json_assets():
@@ -72,16 +107,36 @@ def detect_architecture(model_name: str) -> str:
         _detected_architectures_cache[model_name] = "generic"
         return "generic"
 
-    model_lower = model_name.lower()
+    # Normalize model names for better pattern matching:
+    # - HuggingFace cache names use `--` as `/` separators (models--org--name).
+    # - Claude versions sometimes appear as `claude-3-5-sonnet` (normalize to `claude-3.5-sonnet`).
+    model_lower = model_name.lower().replace("--", "/")
+    import re
+    model_lower = re.sub(r'(claude-\d+)-(\d+)(?=-|$)', r'\1.\2', model_lower)
+
+    # Choose the most specific matching architecture.
+    # Many architectures include broad patterns (e.g. "gpt") that can accidentally
+    # match more specific models (e.g. "gpt-oss"). We resolve this by selecting the
+    # longest matching pattern across all architectures.
+    best_arch = "generic"
+    best_pattern = ""
 
-    # Check each architecture's patterns
     for arch_name, arch_config in _architecture_formats["architectures"].items():
         patterns = arch_config.get("patterns", [])
         for pattern in patterns:
-            if pattern.lower() in model_lower:
-                logger.debug(f"Detected architecture '{arch_name}' for model '{model_name}' (pattern: '{pattern}')")
-                _detected_architectures_cache[model_name] = arch_name
-                return arch_name
+            pat = str(pattern).lower()
+            if not pat:
+                continue
+            if pat in model_lower and len(pat) > len(best_pattern):
+                best_arch = arch_name
+                best_pattern = pat
+
+    if best_arch != "generic":
+        logger.debug(
+            f"Detected architecture '{best_arch}' for model '{model_name}' (pattern: '{best_pattern}')"
+        )
+        _detected_architectures_cache[model_name] = best_arch
+        return best_arch
 
     # Fallback to generic
     logger.debug(f"No specific architecture detected for '{model_name}', using generic")
@@ -147,22 +202,69 @@ def resolve_model_alias(model_name: str, models: Dict[str, Any]) -> str:
     if normalized_model_name != model_name:
         logger.debug(f"Normalized model name '{model_name}' to '{normalized_model_name}'")
 
-    # Check if normalized name is a canonical name
-    if normalized_model_name in models:
-        _resolved_aliases_cache[model_name] = normalized_model_name
-        return normalized_model_name
-
-    # Check if it's an alias of any model (try both original and normalized)
+    # Also support "provider/model" strings by stripping known provider prefixes.
+    stripped_model_name = _strip_provider_prefix(model_name)
+    stripped_normalized_name = _strip_provider_prefix(normalized_model_name)
+
+    def _tail(name: str) -> str:
+        s = str(name or "").strip()
+        if not s or "/" not in s:
+            return s
+        return s.split("/")[-1].strip()
+
+    def _candidates(*names: str) -> List[str]:
+        out: List[str] = []
+        for n in names:
+            s = str(n or "").strip()
+            if not s:
+                continue
+            out.append(s)
+            t = _tail(s)
+            if t and t != s:
+                out.append(t)
+        # Deduplicate while preserving order
+        uniq: List[str] = []
+        seen: set[str] = set()
+        for s in out:
+            if s in seen:
+                continue
+            seen.add(s)
+            uniq.append(s)
+        return uniq
+
+    # Check if any normalized/stripped name is a canonical name.
+    for candidate in _candidates(normalized_model_name, stripped_normalized_name, stripped_model_name):
+        if candidate in models:
+            _resolved_aliases_cache[model_name] = candidate
+            return candidate
+
+    # Check if it's an alias of any model (try both original and normalized).
+    # Some JSON entries intentionally share aliases (e.g. base + variant). Prefer the
+    # most specific canonical model name deterministically.
+    alias_matches: List[str] = []
     for canonical_name, model_info in models.items():
         aliases = model_info.get("aliases", [])
-        if model_name in aliases or normalized_model_name in aliases:
-            logger.debug(f"Resolved alias '{model_name}' to canonical name '{canonical_name}'")
-            _resolved_aliases_cache[model_name] = canonical_name
-            return canonical_name
+        if not isinstance(aliases, list) or not aliases:
+            continue
+        candidates = _candidates(model_name, normalized_model_name, stripped_model_name, stripped_normalized_name)
+        alias_set = {str(a).strip().lower() for a in aliases if isinstance(a, str) and str(a).strip()}
+        cand_set = {str(c).strip().lower() for c in candidates if isinstance(c, str) and str(c).strip()}
+        if alias_set and cand_set and alias_set.intersection(cand_set):
+            alias_matches.append(canonical_name)
+
+    if alias_matches:
+        best = max(alias_matches, key=lambda n: (len(str(n)), str(n)))
+        logger.debug(f"Resolved alias '{model_name}' to canonical name '{best}'")
+        _resolved_aliases_cache[model_name] = best
+        return best
 
     # Return normalized name if no alias found
-    _resolved_aliases_cache[model_name] = normalized_model_name
-    return normalized_model_name
+    fallback = stripped_normalized_name or normalized_model_name
+    fallback_tail = _tail(fallback)
+    if fallback_tail:
+        fallback = fallback_tail
+    _resolved_aliases_cache[model_name] = fallback
+    return fallback
 
 
 def get_model_capabilities(model_name: str) -> Dict[str, Any]:
@@ -199,15 +301,44 @@ def get_model_capabilities(model_name: str) -> Dict[str, Any]:
     # Step 3: Try partial matches for common model naming patterns
     # Use canonical_name (which has been normalized) for better matching
     canonical_lower = canonical_name.lower()
-    for model_key, capabilities in models.items():
-        if model_key.lower() in canonical_lower or canonical_lower in model_key.lower():
+    candidates_name_in_key: List[tuple[int, int, str]] = []
+    candidates_key_in_name: List[tuple[int, str]] = []
+    for model_key in models.keys():
+        if not isinstance(model_key, str) or not model_key.strip():
+            continue
+        key_lower = model_key.lower()
+
+        # Prefer a close "superstring" match where the canonical name is missing a suffix.
+        # Example: "qwen3-next-80b" -> "qwen3-next-80b-a3b"
+        if canonical_lower and canonical_lower in key_lower:
+            extra = max(0, len(key_lower) - len(canonical_lower))
+            candidates_name_in_key.append((extra, len(key_lower), model_key))
+            continue
+
+        # Otherwise, prefer the most specific substring match (e.g. provider/model prefixes).
+        if key_lower in canonical_lower:
+            candidates_key_in_name.append((len(key_lower), model_key))
+
+    best_key: Optional[str] = None
+    best_mode: Optional[str] = None
+    if candidates_name_in_key:
+        candidates_name_in_key.sort(key=lambda x: (x[0], -x[1]))
+        best_key = candidates_name_in_key[0][2]
+        best_mode = "name_in_key"
+    elif candidates_key_in_name:
+        best_key = max(candidates_key_in_name, key=lambda x: x[0])[1]
+        best_mode = "key_in_name"
+
+    if best_key is not None:
+        capabilities = models.get(best_key)
+        if isinstance(capabilities, dict):
             result = capabilities.copy()
             # Remove alias-specific fields
             result.pop("canonical_name", None)
             result.pop("aliases", None)
             if "architecture" not in result:
                 result["architecture"] = detect_architecture(model_name)
-            logger.debug(f"Using capabilities from '{model_key}' for '{model_name}'")
+            logger.debug(f"Using capabilities from '{best_key}' for '{model_name}' (partial match: {best_mode})")
             return result
 
     # Step 4: Fallback to default capabilities based on architecture
@@ -215,16 +346,50 @@ def get_model_capabilities(model_name: str) -> Dict[str, Any]:
     default_caps = _model_capabilities.get("default_capabilities", {}).copy()
     default_caps["architecture"] = architecture
 
-    # Enhance defaults based on architecture
+    # Enhance defaults based on architecture.
+    #
+    # NOTE: `architecture_formats.json.tool_format` describes the *prompted transcript syntax*
+    # for tool calls (e.g. XML-wrapped, <|tool_call|> blocks, etc). Some architectures/models
+    # also support *native tool APIs* (provider-level `tools` payloads) even when their prompted
+    # transcript format is non-native. For those cases, architectures can set an explicit
+    # `default_tool_support` to avoid relying on tool_format heuristics.
     arch_format = get_architecture_format(architecture)
-    if arch_format.get("tool_format") == "native":
+
+    explicit_support = str(arch_format.get("default_tool_support") or "").strip().lower()
+    if explicit_support in {"native", "prompted", "none"}:
+        default_caps["tool_support"] = explicit_support
+    elif arch_format.get("tool_format") == "native":
         default_caps["tool_support"] = "native"
-    elif arch_format.get("tool_format") in ["special_token", "json", "xml", "pythonic"]:
+    elif arch_format.get("tool_format") in ["special_token", "json", "xml", "pythonic", "glm_xml"]:
         default_caps["tool_support"] = "prompted"
     else:
         default_caps["tool_support"] = "none"
 
+    # Propagate architecture-level output wrappers into default capabilities.
+    wrappers = arch_format.get("output_wrappers")
+    if isinstance(wrappers, dict) and wrappers:
+        default_caps["output_wrappers"] = dict(wrappers)
+
     logger.debug(f"Using default capabilities for '{model_name}' (architecture: {architecture})")
+
+    # Emit a one-time warning for unknown models to keep model_capabilities.json up to date.
+    try:
+        raw_name = str(model_name).strip()
+    except Exception:
+        raw_name = ""
+
+    if raw_name and raw_name not in _default_capabilities_warning_cache:
+        _default_capabilities_warning_cache.add(raw_name)
+        logger.warning(
+            "Model not found in model_capabilities.json; falling back to architecture defaults",
+            model_name=raw_name,
+            detected_architecture=architecture,
+            default_tool_support=default_caps.get("tool_support"),
+            next_steps=(
+                "Add this model (or an alias) to abstractcore/abstractcore/assets/model_capabilities.json "
+                "or email contact@abstractcore.ai with the exact model id and provider."
+            ),
+        )
     return default_caps
 
 
@@ -539,4 +704,4 @@ def check_vision_model_compatibility(model_name: str, provider: str = None) -> D
         result['warnings'].append("No max_image_tokens specified")
         result['recommendations'].append("Add max_image_tokens to model capabilities")
     
-    return result
+    return result