abstractcore 2.9.1__py3-none-any.whl → 2.11.4__py3-none-any.whl

abstractcore/core/interface.py

@@ -71,11 +71,12 @@ class AbstractCoreInterface(ABC):
                  max_input_tokens: Optional[int] = None,
                  max_output_tokens: int = 2048,
                  temperature: float = 0.7,
-                 seed: Optional[int] = None,
+                 seed: Optional[int] = -1,
                  debug: bool = False,
                  **kwargs):
         self.model = model
         self.config = kwargs
+        self._capability_registry = None
 
         # Unified token parameters
         self.max_tokens = max_tokens
@@ -84,13 +85,153 @@ class AbstractCoreInterface(ABC):
         
         # Unified generation parameters
         self.temperature = temperature
-        self.seed = seed
+        # Default seed policy: -1 means "random" (do not forward a provider seed).
+        # Accept None for backward compatibility and normalize it to -1.
+        self.seed = -1 if seed is None else seed
         
         self.debug = debug
 
         # Validate token parameters
         self._validate_token_parameters()
 
+    @property
+    def capabilities(self):
+        """Capability registry (voice/audio/vision plugins).
+
+        Lazily created to avoid importing plugin machinery during `import abstractcore`.
+        """
+        if self._capability_registry is None:
+            explicit_prefs = None
+            try:
+                explicit_prefs = self.config.get("capabilities_preferred_backends")
+            except Exception:
+                explicit_prefs = None
+
+            merged_prefs: Dict[str, str] = {}
+
+            # Global config defaults (config-manager) — lowest precedence.
+            try:
+                from ..config.manager import get_config_manager
+
+                stt_backend_id = getattr(getattr(get_config_manager().config, "audio", None), "stt_backend_id", None)
+            except Exception:
+                stt_backend_id = None
+            if isinstance(stt_backend_id, str) and stt_backend_id.strip():
+                merged_prefs["audio"] = stt_backend_id.strip()
+
+            # Per-instance explicit preferences — highest precedence.
+            if isinstance(explicit_prefs, dict):
+                for k, v in explicit_prefs.items():
+                    ks = str(k or "").strip()
+                    vs = str(v or "").strip()
+                    if ks and vs:
+                        merged_prefs[ks] = vs
+
+            from ..capabilities.registry import CapabilityRegistry
+
+            self._capability_registry = CapabilityRegistry(self, preferred_backends=merged_prefs or None)
+        return self._capability_registry
+
+    @property
+    def voice(self):
+        return self.capabilities.voice
+
+    @property
+    def audio(self):
+        return self.capabilities.audio
+
+    @property
+    def vision(self):
+        return self.capabilities.vision
+
+    def generate_with_outputs(
+        self,
+        prompt: str,
+        *,
+        outputs: Optional[Dict[str, Any]] = None,
+        artifact_store: Optional[Any] = None,
+        **kwargs,
+    ):
+        """Convenience wrapper: run `generate()` then optional deterministic capability calls.
+
+        This intentionally does *not* change `generate()` semantics.
+
+        `outputs` is a small, explicit contract (v0):
+        - {"tts": {...}}: calls `core.voice.tts(...)` after text generation.
+          - default text source is the LLM response content.
+        - {"t2i": {...}}: calls `core.vision.t2i(...)` after text generation.
+          - default prompt source is the LLM response content.
+
+        If `artifact_store` is provided, it is passed through to capability calls.
+        """
+        from ..capabilities.types import GenerateWithOutputsResult
+
+        stream = bool(kwargs.get("stream", False))
+        if stream:
+            raise ValueError("generate_with_outputs does not support stream=True (v0)")
+
+        resp = self.generate(prompt, **kwargs)
+        out: Dict[str, Any] = {}
+
+        cfg = outputs if isinstance(outputs, dict) else {}
+        if cfg.get("tts"):
+            tts_cfg = cfg.get("tts")
+            tts_cfg = tts_cfg if isinstance(tts_cfg, dict) else {}
+            text = tts_cfg.get("text")
+            if text is None:
+                text = getattr(resp, "content", "") or ""
+            out["tts"] = self.voice.tts(
+                str(text),
+                voice=tts_cfg.get("voice"),
+                format=str(tts_cfg.get("format") or "wav"),
+                artifact_store=artifact_store,
+                run_id=tts_cfg.get("run_id"),
+                tags=tts_cfg.get("tags"),
+                metadata=tts_cfg.get("metadata"),
+            )
+
+        if cfg.get("t2i"):
+            t2i_cfg = cfg.get("t2i")
+            t2i_cfg = t2i_cfg if isinstance(t2i_cfg, dict) else {}
+            img_prompt = t2i_cfg.get("prompt")
+            if img_prompt is None:
+                img_prompt = getattr(resp, "content", "") or ""
+            out["t2i"] = self.vision.t2i(
+                str(img_prompt),
+                artifact_store=artifact_store,
+                run_id=t2i_cfg.get("run_id"),
+                tags=t2i_cfg.get("tags"),
+                metadata=t2i_cfg.get("metadata"),
+                **{k: v for k, v in t2i_cfg.items() if k not in {"prompt", "run_id", "tags", "metadata"}},
+            )
+
+        return GenerateWithOutputsResult(response=resp, outputs=out)
+
+    # Unified generation parameter accessors (provider-agnostic)
+    def get_temperature(self) -> float:
+        return float(self.temperature)
+
+    def set_temperature(self, temperature: float) -> None:
+        self.temperature = float(temperature)
+
+    def get_seed(self) -> int:
+        try:
+            return int(self.seed)  # type: ignore[arg-type]
+        except Exception:
+            return -1
+
+    def set_seed(self, seed: Optional[int]) -> None:
+        # Normalize: None or negative -> -1 (random)
+        if seed is None:
+            self.seed = -1
+            return
+        try:
+            seed_i = int(seed)
+        except Exception:
+            self.seed = -1
+            return
+        self.seed = seed_i if seed_i >= 0 else -1
+
     @abstractmethod
     def generate(self,
                 prompt: str,
@@ -99,6 +240,7 @@ class AbstractCoreInterface(ABC):
                 tools: Optional[List[Dict[str, Any]]] = None,
                 media: Optional[List[Union[str, Dict[str, Any], 'MediaContent']]] = None,
                 stream: bool = False,
+                thinking: Optional[Union[bool, str]] = None,
                 **kwargs) -> Union[GenerateResponse, Iterator[GenerateResponse]]:
         """
         Generate response from the LLM.
@@ -110,6 +252,7 @@ class AbstractCoreInterface(ABC):
             tools: Optional list of available tools
             media: Optional list of media files (file paths, MediaContent objects, or dicts)
             stream: Whether to stream the response
+            thinking: Unified thinking/reasoning control (best-effort across providers/models)
             **kwargs: Additional provider-specific parameters
 
         Returns:
@@ -122,6 +265,11 @@ class AbstractCoreInterface(ABC):
         """Get list of capabilities supported by this provider"""
         pass
 
+    @abstractmethod
+    def unload_model(self, model_name: str) -> None:
+        """Unload/cleanup resources for a specific model (best-effort)."""
+        pass
+
     def validate_config(self) -> bool:
         """Validate provider configuration"""
         return True
@@ -354,4 +502,4 @@ class AbstractCoreInterface(ABC):
             for warning in warnings:
                 lines.append(f"  • {warning}")
 
-        return "\n".join(lines)
+        return "\n".join(lines)

abstractcore/core/session.py

@@ -34,8 +34,8 @@ class BasicSession:
                  recovery_timeout: Optional[float] = None,
                  auto_compact: bool = False,
                  auto_compact_threshold: int = 6000,
-                 temperature: Optional[float] = None,
-                 seed: Optional[int] = None,
+                 temperature: Optional[float] = 0.7,
+                 seed: Optional[int] = -1,
                  enable_tracing: bool = False):
         """Initialize basic session
 
@@ -48,8 +48,8 @@ class BasicSession:
             recovery_timeout: Circuit breaker recovery timeout
             auto_compact: Enable automatic conversation compaction
             auto_compact_threshold: Token threshold for auto-compaction
-            temperature: Default temperature for generation (0.0-1.0)
-            seed: Default seed for deterministic generation
+            temperature: Default temperature for generation (provider-agnostic)
+            seed: Default seed for deterministic generation (-1 means random/unset)
             enable_tracing: Enable interaction tracing for observability
         """
 
@@ -63,9 +63,15 @@ class BasicSession:
         self.auto_compact_threshold = auto_compact_threshold
         self._original_session = None  # Track if this is a compacted session
 
-        # Store session-level generation parameters
-        self.temperature = temperature
-        self.seed = seed
+        # Store session-level generation parameters.
+        self.temperature = None if temperature is None else float(temperature)
+        # Normalize: None or negative -> -1 (random/unset)
+        try:
+            self.seed = -1 if seed is None else int(seed)
+        except Exception:
+            self.seed = -1
+        if isinstance(self.seed, int) and self.seed < 0:
+            self.seed = -1
 
         # Setup interaction tracing
         self.enable_tracing = enable_tracing
@@ -218,7 +224,7 @@ class BasicSession:
         # Add session-level parameters if not overridden in kwargs
         if 'temperature' not in kwargs and self.temperature is not None:
             kwargs['temperature'] = self.temperature
-        if 'seed' not in kwargs and self.seed is not None:
+        if 'seed' not in kwargs and isinstance(self.seed, int) and self.seed >= 0:
             kwargs['seed'] = self.seed
 
         # Add trace metadata if tracing is enabled
@@ -329,7 +335,7 @@ class BasicSession:
         # Add session-level parameters if not overridden in kwargs
         if 'temperature' not in kwargs and self.temperature is not None:
             kwargs['temperature'] = self.temperature
-        if 'seed' not in kwargs and self.seed is not None:
+        if 'seed' not in kwargs and isinstance(self.seed, int) and self.seed >= 0:
             kwargs['seed'] = self.seed
 
         # Add trace metadata if tracing is enabled
@@ -1143,4 +1149,4 @@ class BasicSession:
             >>> print(f"First trace: {traces[0]['trace_id']}")
             >>> print(f"Tokens used: {traces[0]['response']['usage']}")
         """
-        return self.interaction_traces.copy()
+        return self.interaction_traces.copy()

abstractcore/download.py

@@ -212,7 +212,7 @@ async def _download_huggingface(
             status=DownloadStatus.ERROR,
             message=(
                 "huggingface_hub is not installed. "
-                "Install with: pip install abstractcore[huggingface]"
+                "Install with: pip install \"abstractcore[huggingface]\""
             ),
         )
         return

abstractcore/embeddings/manager.py

@@ -8,6 +8,7 @@ Production-ready embedding generation with SOTA models and efficient serving.
 import hashlib
 import pickle
 import atexit
+import os
 import sys
 import builtins
 import warnings
@@ -124,7 +125,8 @@ class EmbeddingManager:
         cache_dir: Optional[Path] = None,
         cache_size: int = 1000,
         output_dims: Optional[int] = None,
-        trust_remote_code: bool = False
+        trust_remote_code: bool = False,
+        strict: Optional[bool] = None,
     ):
         """Initialize the embedding manager.
 
@@ -138,7 +140,13 @@ class EmbeddingManager:
             cache_size: Maximum number of embeddings to cache in memory
             output_dims: Output dimensions for Matryoshka truncation (if supported by provider)
             trust_remote_code: Whether to trust remote code (HuggingFace only)
+            strict: If true, raise on provider/model failures instead of returning zero vectors.
         """
+        if strict is None:
+            strict_raw = str(os.environ.get("ABSTRACTCORE_EMBEDDINGS_STRICT", "") or "").strip().lower()
+            strict = strict_raw in {"1", "true", "yes", "on"}
+        self.strict = bool(strict)
+
         # Load configuration defaults, but ONLY if parameters weren't explicitly provided
         self._load_config_defaults(model, provider)
 
@@ -277,7 +285,10 @@ class EmbeddingManager:
         """Load the HuggingFace embedding model with optimal backend and reduced warnings."""
         try:
             if sentence_transformers is None:
-                raise ImportError("sentence-transformers is required but not installed")
+                raise ImportError(
+                    "sentence-transformers is required but not installed. "
+                    "Install with: pip install \"abstractcore[embeddings]\""
+                )
 
             # Set HuggingFace cache directory (sentence-transformers uses this automatically)
             import os
@@ -333,7 +344,8 @@ class EmbeddingManager:
         except ImportError:
             raise ImportError(
                 "sentence-transformers is required for embedding functionality. "
-                "Install with: pip install sentence-transformers"
+                "Install with: pip install \"abstractcore[embeddings]\" (recommended) "
+                "or: pip install sentence-transformers"
             )
         except Exception as e:
             logger.error(f"Failed to load embedding model {self.model_id}: {e}")
@@ -676,7 +688,8 @@ class EmbeddingManager:
 
         except Exception as e:
             logger.error(f"Failed to embed text with {self.provider}: {e}")
-            # Return zero vector as fallback
+            if self.strict:
+                raise
             dim = self.output_dims or self.get_dimension()
             return [0.0] * dim
 
@@ -759,7 +772,8 @@ class EmbeddingManager:
 
             except Exception as e:
                 logger.error(f"Failed to embed batch with {self.provider}: {e}")
-                # Fill with zero vectors as fallback
+                if self.strict:
+                    raise
                 dim = self.output_dims or self.get_dimension()
                 zero_embedding = [0.0] * dim
                 for idx in uncached_indices:
@@ -1262,4 +1276,4 @@ class EmbeddingManager:
     def save_caches(self):
         """Explicitly save both caches to disk."""
         self._save_persistent_cache()
-        self._save_normalized_cache()
+        self._save_normalized_cache()

abstractcore/endpoint/__init__.py

@@ -0,0 +1,2 @@
+"""AbstractCore single-model OpenAI-compatible endpoint server."""
+