Merge branch 'main' into feat/llm-providers-expansion

docs/guides/llm-integrations.md

@@ -62,7 +62,7 @@ Four factors drive provider selection, each optimized for different use cases:
 
 **Accuracy** matters most in high-stakes decisions: clinical contraindication checks, credit committee reasoning, and legal document analysis. Frontier models like Claude or GPT-4 available through `LiteLLM` provide the strongest reasoning capabilities.
 
-**Data residency** constraints eliminate cloud providers for classified or HIPAA-regulated workloads. `HuggingFaceLLM` with local model paths enables fully air-gapped deployments without network calls.
+**Data residency** constraints eliminate cloud providers for classified or HIPAA-regulated workloads. `HuggingFaceLLM` with local model paths, or `Ollama` pointed at a local server, both enable fully air-gapped deployments without network calls.
 
 **Cost at scale** favors high-throughput providers like Novita AI for bulk extraction pipelines processing thousands of documents per hour where per-token costs accumulate quickly.
 
@@ -198,6 +198,79 @@ print(risk.risk_level, risk.days_to_deadline)
 
 Model selection follows the same tier structure as the other providers: a Haiku model for high-volume classification where cost matters more than depth, a Sonnet model as the default for most extraction and reasoning tasks, an Opus model when a task genuinely needs the deepest reasoning available and latency/cost are secondary. Check Anthropic's docs for the current model identifiers, since they're versioned and change over time.
 
+## Gemini — Long Context and Multimodal Input
+
+**Gemini** is Google's model family, with a context window large enough to hold entire codebases or long regulatory filings in a single call, and native support for image and document input alongside text. Reach for it when a task needs to reference a large amount of source material at once, or when the input isn't plain text.
+
+The `Gemini` provider tries the newer `google-genai` SDK first and falls back to the older `google-generativeai` package if that's what's installed. Install with `pip install "semantica[llm-gemini]"` (or `pip install google-genai`) before using this provider.
+
+```python
+from semantica.llms import Gemini
+
+gemini = Gemini(model="gemini-pro", api_key="YOUR_GEMINI_KEY")
+# api_key falls back to the GEMINI_API_KEY environment variable
+
+if not gemini.is_available():
+    raise RuntimeError("Gemini provider not configured - set GEMINI_API_KEY")
+
+response = gemini.generate(
+    "Summarize the key obligations in a standard NDA in three bullet points."
+)
+print(response)
+
+data = gemini.generate_structured(
+    "Extract the party names and effective date from: "
+    "This Agreement is entered into between Acme Corp and Globex LLC, "
+    "effective January 1, 2026."
+)
+print(data)
+```
+
+## Ollama — Local, Air-Gapped Inference
+
+**Ollama** runs models entirely on your own machine, with no API key and no outbound network call. It's the right choice for air-gapped environments, offline development, or any workload where the source data can't leave the local network.
+
+Unlike the other providers here, `Ollama` takes a `base_url` instead of an `api_key`. It talks to a local Ollama server over HTTP. Start the server with `ollama serve` and pull a model with `ollama pull llama2` before using this provider. Install the Python client with `pip install "semantica[llm-ollama]"` (or `pip install ollama`).
+
+```python
+from semantica.llms import Ollama
+
+llm = Ollama(model="llama2", base_url="http://localhost:11434")
+
+if not llm.is_available():
+    raise RuntimeError("Ollama provider not configured - is 'ollama serve' running?")
+
+response = llm.generate("Explain the difference between a hash map and a tree map.")
+print(response)
+```
+
+`is_available()` for Ollama does a real connectivity check (it calls the server's `list()` endpoint), unlike the API-key-based providers above, so a `False` here usually means the server isn't running rather than a missing credential.
+
+## DeepSeek — Budget Reasoning at Scale
+
+**DeepSeek** exposes an OpenAI-compatible API at a fraction of the cost of the larger US providers, with reasoning quality that holds up well for extraction and classification work. It's a reasonable default when you're processing a large volume of documents and don't need the deepest reasoning tier.
+
+Install with `pip install "semantica[llm-deepseek]"` (or `pip install openai`, since DeepSeek is accessed through the OpenAI client pointed at a different base URL).
+
+```python
+from semantica.llms import DeepSeek
+
+llm = DeepSeek(model="deepseek-chat", api_key="YOUR_DEEPSEEK_KEY")
+# api_key falls back to the DEEPSEEK_API_KEY environment variable
+
+if not llm.is_available():
+    raise RuntimeError("DeepSeek provider not configured - set DEEPSEEK_API_KEY")
+
+response = llm.generate("List three risks of using a floating IP in a Kubernetes ingress.")
+print(response)
+
+data = llm.generate_structured(
+    "Extract the CVE ID and affected product from: "
+    "CVE-2024-3400 affects PAN-OS GlobalProtect gateways."
+)
+print(data)
+```
+
 ## LiteLLM — One Interface, 100+ Providers
 
 **LiteLLM** is a universal adapter that provides a single interface to over 100 different LLM providers, including Anthropic Claude, Azure OpenAI, AWS Bedrock, Google Vertex AI, and local Ollama instances. It acts as a translation layer, converting your unified API calls into provider-specific requests, enabling easy switching between providers without code changes.
@@ -361,30 +434,32 @@ for t in triplets:
 
 ## Novita AI — Cost-Efficient Bulk Extraction
 
-Novita AI exposes an OpenAI-compatible API and is available as a built-in provider for the extraction layer. It is accessed differently from the `semantica.llms` classes — through `create_provider` from `semantica.semantic_extract.providers` — making it the right choice for high-volume NER pipelines where per-call cost matters.
+**Novita AI** exposes an OpenAI-compatible API at low per-call cost, making it a reasonable choice for high-volume NER pipelines where cost matters more than getting the single best answer.
+
+Install with `pip install "semantica[llm-novita]"` (or `pip install openai`, since Novita is accessed through the OpenAI client pointed at a different base URL).
+
+```python
+from semantica.llms import Novita
+
+llm = Novita(model="deepseek/deepseek-v3.2", api_key="YOUR_NOVITA_KEY")
+# api_key falls back to the NOVITA_API_KEY environment variable
+
+if not llm.is_available():
+    raise RuntimeError("Novita provider not configured - set NOVITA_API_KEY")
+
+response = llm.generate("Summarize the Basel III leverage ratio requirement.")
+
+data = llm.generate_structured(
+    "Extract drug names and dosages from: "
+    "Patient received warfarin 5mg daily, aspirin 75mg daily, metformin 500mg twice daily."
+)
+```
+
+Novita is also reachable as a provider name string for the NER interface, without going through the `Novita` class directly:
 
 ```python
-from semantica.semantic_extract.providers import create_provider
 from semantica.semantic_extract import NamedEntityRecognizer
 
-# create_provider pools instances — same key reuses the same object
-provider = create_provider(
-    "novita",
-    api_key="YOUR_NOVITA_KEY",       # or set NOVITA_API_KEY env var
-    model="deepseek/deepseek-v3.2",  # default model
-)
-
-if provider.is_available():
-    # Plain generation
-    response = provider.generate("Summarise the Basel III leverage ratio requirement.")
-
-    # Structured extraction — returns parsed dict
-    data = provider.generate_structured(
-        "Extract drug names and dosages from: "
-        "Patient received warfarin 5mg daily, aspirin 75mg daily, metformin 500mg twice daily."
-    )
-
-# Use Novita through the NER interface — provider name as string
 ner = NamedEntityRecognizer(
     methods=["llm"],
     provider="novita",
@@ -394,11 +469,9 @@ entities = ner.extract_entities(
     "CVE-2024-3400 is exploited by UNC3886 targeting PAN-OS GlobalProtect."
 )
 for e in entities:
-    print("{} ({}) — conf={:.2f}".format(e.text, e.label, e.confidence))
+    print("{} ({}) conf={:.2f}".format(e.text, e.label, e.confidence))
 ```
 
-Novita requires the `openai` Python client under the hood — install with `pip install "semantica[llm-openai]"` or `pip install openai`.
-
 ## Domain Examples
 
 <Tabs>

pyproject.toml

@@ -107,11 +107,12 @@ llm-gemini = ["google-genai>=0.1.0"]
 llm-anthropic = ["anthropic>=0.122.0"]
 llm-ollama = ["ollama>=0.1.0"]
 llm-deepseek = ["openai>=1.0.0"]
+llm-novita = ["openai>=1.0.0"]
 llm-litellm = ["litellm>=1.83.9"]
 llm-instructor = ["instructor>=1.15.3"]
 
 llm-all = [
-  "semantica[llm-openai,llm-groq,llm-gemini,llm-anthropic,llm-ollama,llm-deepseek,llm-litellm,llm-instructor]"
+  "semantica[llm-openai,llm-groq,llm-gemini,llm-anthropic,llm-ollama,llm-deepseek,llm-novita,llm-litellm,llm-instructor]"
 ]
 
 # ---- Document Parsing ----

semantica/llms/__init__.py

@@ -11,22 +11,26 @@ Supported Providers:
     - HuggingFaceLLM: HuggingFace Transformers for local LLM inference
     - LiteLLM: Unified interface to 100+ LLM providers (OpenAI, Anthropic, Groq, Azure, Bedrock, Vertex AI, etc.)
     - Anthropic: Anthropic Claude API (Claude sonnet, Opus, Haiku, etc.)
+    - Gemini: Google Gemini API
+    - Ollama: Local models served through Ollama
+    - DeepSeek: DeepSeek's OpenAI-compatible API
+    - Novita: Novita AI's OpenAI-compatible API
 
 Example Usage:
     >>> from semantica.llms import Groq, OpenAI, HuggingFaceLLM, LiteLLM, Anthropic
-    >>> 
+    >>>
     >>> # Groq provider
     >>> groq = Groq(model="llama-3.1-8b-instant", api_key="your-key")
     >>> response = groq.generate("Hello, world!")
-    >>> 
+    >>>
     >>> # OpenAI provider
     >>> openai = OpenAI(model="gpt-4", api_key="your-key")
     >>> response = openai.generate("Hello, world!")
-    >>> 
+    >>>
     >>> # HuggingFace LLM provider
     >>> hf = HuggingFaceLLM(model_name="gpt2")
     >>> response = hf.generate("Hello, world!")
-    >>> 
+    >>>
     >>> # LiteLLM provider (supports 100+ LLMs)
     >>> llm = LiteLLM(model="openai/gpt-4o", api_key="your-key")
     >>> response = llm.generate("Hello, world!")
@@ -37,6 +41,22 @@ Example Usage:
     >>> # Anthropic provider
     >>> claude = Anthropic(model="claude-sonnet-4-6", api_key="the-key")
     >>> response = claude.generate("Hello, world!")
+    >>>
+    >>> # Gemini provider
+    >>> gemini = Gemini(model="gemini-pro", api_key="your-key")
+    >>> response = gemini.generate("Hello, world!")
+    >>>
+    >>> # Ollama provider (local, no api_key)
+    >>> ollama = Ollama(model="llama2")
+    >>> response = ollama.generate("Hello, world!")
+    >>>
+    >>> # DeepSeek provider
+    >>> deepseek = DeepSeek(model="deepseek-chat", api_key="your-key")
+    >>> response = deepseek.generate("Hello, world!")
+    >>>
+    >>> # Novita provider
+    >>> novita = Novita(model="deepseek/deepseek-v3.2", api_key="your-key")
+    >>> response = novita.generate("Hello, world!")
 
 Author: Semantica Contributors
 License: MIT
@@ -47,6 +67,19 @@ from .openai import OpenAI
 from .huggingface import HuggingFaceLLM
 from .litellm import LiteLLM
 from .anthropic import Anthropic
+from .gemini import Gemini
+from .ollama import Ollama
+from .deepseek import DeepSeek
+from .novita import Novita
 
-__all__ = ["Groq", "OpenAI", "HuggingFaceLLM", "LiteLLM", "Anthropic"]
-
+__all__ = [
+    "Groq",
+    "OpenAI",
+    "HuggingFaceLLM",
+    "LiteLLM",
+    "Anthropic",
+    "Gemini",
+    "Ollama",
+    "DeepSeek",
+    "Novita",
+]

semantica/llms/deepseek.py

@@ -0,0 +1,111 @@
+"""
+DeepSeek LLM Provider
+
+Wrapper for DeepSeek API provider with clean interface.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from ..semantic_extract.providers import DeepSeekProvider
+from ..utils.exceptions import ProcessingError
+from ..utils.logging import get_logger
+
+logger = get_logger("llms.deepseek")
+
+
+class DeepSeek:
+    """
+    DeepSeek LLM provider wrapper.
+
+    Provides clean interface to DeepSeek's OpenAI-compatible API.
+
+    Example:
+        >>> from semantica.llms import DeepSeek
+        >>> llm = DeepSeek(model="deepseek-chat", api_key="your-key")
+        >>> response = llm.generate("What is AI?")
+    """
+
+    def __init__(
+        self,
+        model: str = "deepseek-chat",
+        api_key: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Initialize DeepSeek provider.
+
+        Args:
+            model: Model name (default: "deepseek-chat")
+            api_key: DeepSeek API key (default: from DEEPSEEK_API_KEY env var)
+            **kwargs: Additional provider options
+        """
+        self.provider = DeepSeekProvider(api_key=api_key, model=model, **kwargs)
+        self.model = model
+        self.api_key = api_key
+
+    def is_available(self) -> bool:
+        """Check if DeepSeek provider is available."""
+        return self.provider.is_available()
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from prompt.
+
+        Args:
+            prompt: Input prompt text
+            **kwargs: Generation options (temperature, max_tokens, etc.)
+
+        Returns:
+            Generated text response
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "DeepSeek provider not available. Set DEEPSEEK_API_KEY or pass api_key."
+            )
+        return self.provider.generate(prompt, **kwargs)
+
+    def generate_structured(self, prompt: str, **kwargs) -> Union[Dict[str, Any], List[Any]]:
+        """
+        Generate structured JSON output.
+
+        Args:
+            prompt: Input prompt text
+            **kwargs: Generation options
+
+        Returns:
+            Parsed JSON response. A dict for a top-level JSON object, or a
+            list if the model returns a top-level JSON array.
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "DeepSeek provider not available. Set DEEPSEEK_API_KEY or pass api_key."
+            )
+        return self.provider.generate_structured(prompt, **kwargs)
+
+    def generate_typed(self, prompt: str, schema: Any, max_retries: int = 3, **kwargs) -> Any:
+        """
+        Generate output validated against a Pydantic schema.
+
+        Args:
+            prompt: Input prompt text
+            schema: Pydantic model class to validate the output against
+            max_retries: Number of retries if validation fails (default: 3)
+            **kwargs: Generation options
+
+        Returns:
+            An instance of `schema`, populated from the model's response
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "DeepSeek provider not available. Set DEEPSEEK_API_KEY or pass api_key."
+            )
+        return self.provider.generate_typed(prompt, schema, max_retries=max_retries, **kwargs)

semantica/llms/gemini.py

@@ -0,0 +1,111 @@
+"""
+Gemini LLM Provider
+
+Wrapper for Google Gemini API provider with clean interface.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from ..semantic_extract.providers import GeminiProvider
+from ..utils.exceptions import ProcessingError
+from ..utils.logging import get_logger
+
+logger = get_logger("llms.gemini")
+
+
+class Gemini:
+    """
+    Google Gemini LLM provider wrapper.
+
+    Provides clean interface to Google's Gemini API.
+
+    Example:
+        >>> from semantica.llms import Gemini
+        >>> gemini = Gemini(model="gemini-pro", api_key="your-key")
+        >>> response = gemini.generate("What is AI?")
+    """
+
+    def __init__(
+        self,
+        model: str = "gemini-pro",
+        api_key: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Initialize Gemini provider.
+
+        Args:
+            model: Model name (default: "gemini-pro")
+            api_key: Gemini API key (default: from GEMINI_API_KEY env var)
+            **kwargs: Additional provider options
+        """
+        self.provider = GeminiProvider(api_key=api_key, model=model, **kwargs)
+        self.model = model
+        self.api_key = api_key
+
+    def is_available(self) -> bool:
+        """Check if Gemini provider is available."""
+        return self.provider.is_available()
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from prompt.
+
+        Args:
+            prompt: Input prompt text
+            **kwargs: Generation options (temperature, max_tokens, etc.)
+
+        Returns:
+            Generated text response
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "Gemini provider not available. Set GEMINI_API_KEY or pass api_key."
+            )
+        return self.provider.generate(prompt, **kwargs)
+
+    def generate_structured(self, prompt: str, **kwargs) -> Union[Dict[str, Any], List[Any]]:
+        """
+        Generate structured JSON output.
+
+        Args:
+            prompt: Input prompt text
+            **kwargs: Generation options
+
+        Returns:
+            Parsed JSON response. A dict for a top-level JSON object, or a
+            list if the model returns a top-level JSON array.
+
+        Raises:
+            ProcessingError: If provider is not available or parsing fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "Gemini provider not available. Set GEMINI_API_KEY or pass api_key."
+            )
+        return self.provider.generate_structured(prompt, **kwargs)
+
+    def generate_typed(self, prompt: str, schema: Any, max_retries: int = 3, **kwargs) -> Any:
+        """
+        Generate output validated against a Pydantic schema.
+
+        Args:
+            prompt: Input prompt text
+            schema: Pydantic model class to validate the output against
+            max_retries: Number of retries if validation fails (default: 3)
+            **kwargs: Generation options
+
+        Returns:
+            An instance of `schema`, populated from the model's response
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "Gemini provider not available. Set GEMINI_API_KEY or pass api_key."
+            )
+        return self.provider.generate_typed(prompt, schema, max_retries=max_retries, **kwargs)

semantica/llms/novita.py

@@ -0,0 +1,111 @@
+"""
+Novita LLM Provider
+
+Wrapper for Novita AI's OpenAI-compatible API with clean interface.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from ..semantic_extract.providers import NovitaProvider
+from ..utils.exceptions import ProcessingError
+from ..utils.logging import get_logger
+
+logger = get_logger("llms.novita")
+
+
+class Novita:
+    """
+    Novita AI LLM provider wrapper.
+
+    Provides clean interface to Novita's OpenAI-compatible API.
+
+    Example:
+        >>> from semantica.llms import Novita
+        >>> llm = Novita(model="deepseek/deepseek-v3.2", api_key="your-key")
+        >>> response = llm.generate("What is AI?")
+    """
+
+    def __init__(
+        self,
+        model: str = "deepseek/deepseek-v3.2",
+        api_key: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Initialize Novita provider.
+
+        Args:
+            model: Model name (default: "deepseek/deepseek-v3.2")
+            api_key: Novita API key (default: from NOVITA_API_KEY env var)
+            **kwargs: Additional provider options
+        """
+        self.provider = NovitaProvider(api_key=api_key, model=model, **kwargs)
+        self.model = model
+        self.api_key = api_key
+
+    def is_available(self) -> bool:
+        """Check if Novita provider is available."""
+        return self.provider.is_available()
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from prompt.
+
+        Args:
+            prompt: Input prompt text
+            **kwargs: Generation options (temperature, max_tokens, etc.)
+
+        Returns:
+            Generated text response
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "Novita provider not available. Set NOVITA_API_KEY or pass api_key."
+            )
+        return self.provider.generate(prompt, **kwargs)
+
+    def generate_structured(self, prompt: str, **kwargs) -> Union[Dict[str, Any], List[Any]]:
+        """
+        Generate structured JSON output.
+
+        Args:
+            prompt: Input prompt text
+            **kwargs: Generation options
+
+        Returns:
+            Parsed JSON response. A dict for a top-level JSON object, or a
+            list if the model returns a top-level JSON array.
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "Novita provider not available. Set NOVITA_API_KEY or pass api_key."
+            )
+        return self.provider.generate_structured(prompt, **kwargs)
+
+    def generate_typed(self, prompt: str, schema: Any, max_retries: int = 3, **kwargs) -> Any:
+        """
+        Generate output validated against a Pydantic schema.
+
+        Args:
+            prompt: Input prompt text
+            schema: Pydantic model class to validate the output against
+            max_retries: Number of retries if validation fails (default: 3)
+            **kwargs: Generation options
+
+        Returns:
+            An instance of `schema`, populated from the model's response
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "Novita provider not available. Set NOVITA_API_KEY or pass api_key."
+            )
+        return self.provider.generate_typed(prompt, schema, max_retries=max_retries, **kwargs)

semantica/llms/ollama.py

@@ -0,0 +1,116 @@
+"""
+Ollama LLM Provider
+
+Wrapper for local Ollama models with clean interface.
+"""
+
+from typing import Any, Dict, List, Union
+
+from ..semantic_extract.providers import OllamaProvider
+from ..utils.exceptions import ProcessingError
+from ..utils.logging import get_logger
+
+logger = get_logger("llms.ollama")
+
+
+class Ollama:
+    """
+    Ollama LLM provider wrapper.
+
+    Provides clean interface to a local Ollama server. Unlike the other
+    providers here, this one has no API key. It talks to an Ollama
+    instance over HTTP, so make sure `ollama serve` is running first.
+
+    Example:
+        >>> from semantica.llms import Ollama
+        >>> llm = Ollama(model="llama2")
+        >>> response = llm.generate("What is AI?")
+    """
+
+    def __init__(
+        self,
+        model: str = "llama2",
+        base_url: str = "http://localhost:11434",
+        **kwargs
+    ):
+        """
+        Initialize Ollama provider.
+
+        Args:
+            model: Model name (default: "llama2")
+            base_url: Ollama server URL (default: "http://localhost:11434")
+            **kwargs: Additional provider options
+        """
+        self.provider = OllamaProvider(base_url=base_url, model=model, **kwargs)
+        self.model = model
+        self.base_url = base_url
+
+    def is_available(self) -> bool:
+        """Check if Ollama provider is available."""
+        return self.provider.is_available()
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from prompt.
+
+        Args:
+            prompt: Input prompt text
+            **kwargs: Generation options (temperature, max_tokens, etc.)
+
+        Returns:
+            Generated text response
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "Ollama provider not available. Make sure Ollama is running "
+                "and reachable at the configured base_url."
+            )
+        return self.provider.generate(prompt, **kwargs)
+
+    def generate_structured(self, prompt: str, **kwargs) -> Union[Dict[str, Any], List[Any]]:
+        """
+        Generate structured JSON output.
+
+        Args:
+            prompt: Input prompt text
+            **kwargs: Generation options
+
+        Returns:
+            Parsed JSON response. A dict for a top-level JSON object, or a
+            list if the model returns a top-level JSON array.
+
+        Raises:
+            ProcessingError: If provider is not available or parsing fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "Ollama provider not available. Make sure Ollama is running "
+                "and reachable at the configured base_url."
+            )
+        return self.provider.generate_structured(prompt, **kwargs)
+
+    def generate_typed(self, prompt: str, schema: Any, max_retries: int = 3, **kwargs) -> Any:
+        """
+        Generate output validated against a Pydantic schema.
+
+        Args:
+            prompt: Input prompt text
+            schema: Pydantic model class to validate the output against
+            max_retries: Number of retries if validation fails (default: 3)
+            **kwargs: Generation options
+
+        Returns:
+            An instance of `schema`, populated from the model's response
+
+        Raises:
+            ProcessingError: If provider is not available or generation fails
+        """
+        if not self.is_available():
+            raise ProcessingError(
+                "Ollama provider not available. Make sure Ollama is running "
+                "and reachable at the configured base_url."
+            )
+        return self.provider.generate_typed(prompt, schema, max_retries=max_retries, **kwargs)

semantica/semantic_extract/providers.py

@@ -673,6 +673,7 @@ class GeminiProvider(BaseProvider):
         self.model = model
         self.client = None
         self._use_new_genai = False
+        self._legacy_model_cache: Dict[str, Any] = {}
         self._init_client()
 
     def _init_client(self):
@@ -694,6 +695,38 @@ class GeminiProvider(BaseProvider):
             self.client = None
             self.logger.warning("Gemini SDK not installed. Install with: pip install semantica[llm-gemini]")
 
+    def _legacy_client_for(self, requested_model: str):
+        """Return a legacy-SDK GenerativeModel bound to this instance's own
+        API key, for the given model name.
+
+        The legacy google-generativeai package keeps its API key as
+        module-level state (genai.configure()), so any GenerativeModel built
+        by a different GeminiProvider instance in the same process can leave
+        that state pointing at a different key. Re-asserting configure()
+        with this instance's key right before use, instead of only once at
+        construction, keeps sequential calls across instances from reading
+        each other's credentials. A cache keyed by model name avoids
+        rebuilding a GenerativeModel on every call for the common case of
+        one model being reused.
+        """
+        try:
+            import google.generativeai as old_genai
+            old_genai.configure(api_key=self.api_key)
+        except Exception:
+            # _init_client() already required this import to reach the
+            # legacy path in the first place, so this only happens when
+            # self.client was injected directly (tests). Fall back to it
+            # without reasserting credentials rather than failing calls
+            # that never needed the real SDK.
+            return self.client
+        if requested_model == self.model:
+            return self.client
+        cached = self._legacy_model_cache.get(requested_model)
+        if cached is None:
+            cached = old_genai.GenerativeModel(requested_model)
+            self._legacy_model_cache[requested_model] = cached
+        return cached
+
     def is_available(self) -> bool:
         """Check if provider is available."""
         return self.client is not None
@@ -724,7 +757,8 @@ class GeminiProvider(BaseProvider):
             )
             return self._resp_text(resp)
         else:
-            response = self.client.generate_content(prompt, generation_config=config or None)
+            legacy_client = self._legacy_client_for(kwargs.get("model", self.model))
+            response = legacy_client.generate_content(prompt, generation_config=config or None)
             return self._resp_text(response)
 
     def generate_structured(self, prompt: str, **kwargs) -> dict:
@@ -733,15 +767,24 @@ class GeminiProvider(BaseProvider):
             raise ProcessingError("Gemini client not initialized.")
 
         json_prompt = f"{prompt}\n\nReturn the response as valid JSON only."
+
+        config = {}
+        self._add_if_set(config, kwargs, "temperature", "top_p", "top_k", "stop_sequences", "candidate_count")
+        if "max_tokens" in kwargs:
+            config["max_output_tokens"] = kwargs["max_tokens"]
+
         if self._use_new_genai:
             model = kwargs.get("model", self.model)
-            resp = self.client.models.generate_content(model=model, contents=json_prompt)
+            resp = self.client.models.generate_content(
+                model=model, contents=json_prompt, config=config or None
+            )
             try:
                 return self._parse_json(self._resp_text(resp))
             except Exception as e:
                 raise ProcessingError(f"Failed to parse JSON from Gemini response: {e}")
         else:
-            response = self.client.generate_content(json_prompt)
+            legacy_client = self._legacy_client_for(kwargs.get("model", self.model))
+            response = legacy_client.generate_content(json_prompt, generation_config=config or None)
             try:
                 return self._parse_json(self._resp_text(response))
             except Exception as e:
@@ -967,6 +1010,8 @@ class OllamaProvider(BaseProvider):
 
     def is_available(self) -> bool:
         """Check if provider is available."""
+        if self.client is None:
+            self._init_client()
         return self.client is not None
 
     def _build_options(self, kwargs: dict) -> Optional[dict]:
@@ -1018,7 +1063,6 @@ class DeepSeekProvider(BaseProvider):
         self.api_key = api_key or config.get_api_key("deepseek")
         self.base_url = "https://api.deepseek.com/v1"
         self.model = model
-        self.base_url = "https://api.deepseek.com/v1"
         self.client = None
         self._init_client()
 
@@ -1045,7 +1089,7 @@ class DeepSeekProvider(BaseProvider):
             "model": kwargs.get("model", self.model),
             "messages": [{"role": "user", "content": prompt}],
         }
-        self._add_if_set(create_kwargs, kwargs, "temperature", "max_tokens")
+        self._add_if_set(create_kwargs, kwargs, "temperature", "max_tokens", "top_p", "frequency_penalty", "presence_penalty", "seed", "stop", "user")
 
         response = self.client.chat.completions.create(**create_kwargs)
         return response.choices[0].message.content
@@ -1058,8 +1102,9 @@ class DeepSeekProvider(BaseProvider):
         create_kwargs = {
             "model": kwargs.get("model", self.model),
             "messages": [{"role": "user", "content": prompt}],
+            "response_format": {"type": "json_object"},
         }
-        self._add_if_set(create_kwargs, kwargs, "temperature", "max_tokens")
+        self._add_if_set(create_kwargs, kwargs, "temperature", "max_tokens", "top_p", "frequency_penalty", "presence_penalty", "seed", "stop", "user")
 
         response = self.client.chat.completions.create(**create_kwargs)
         try:
@@ -1103,7 +1148,7 @@ class NovitaProvider(BaseProvider):
             "model": kwargs.get("model", self.model),
             "messages": [{"role": "user", "content": prompt}],
         }
-        self._add_if_set(create_kwargs, kwargs, "temperature", "max_tokens")
+        self._add_if_set(create_kwargs, kwargs, "temperature", "max_tokens", "top_p", "frequency_penalty", "presence_penalty", "seed", "stop", "user")
 
         response = self.client.chat.completions.create(**create_kwargs)
         return response.choices[0].message.content
@@ -1118,7 +1163,7 @@ class NovitaProvider(BaseProvider):
             "messages": [{"role": "user", "content": prompt}],
             "response_format": {"type": "json_object"},
         }
-        self._add_if_set(create_kwargs, kwargs, "temperature", "max_tokens")
+        self._add_if_set(create_kwargs, kwargs, "temperature", "max_tokens", "top_p", "frequency_penalty", "presence_penalty", "seed", "stop", "user")
 
         response = self.client.chat.completions.create(**create_kwargs)
         try:

tests/test_llm_deepseek.py

@@ -0,0 +1,80 @@
+"""Tests for the DeepSeek LLM provider wrapper (semantica.llms.DeepSeek)."""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from semantica.llms import DeepSeek
+from semantica.utils.exceptions import ProcessingError
+
+
+def test_construction_stores_model_and_api_key():
+    llm = DeepSeek(model="deepseek-chat", api_key="fake-key")
+    assert llm.model == "deepseek-chat"
+    assert llm.api_key == "fake-key"
+
+
+def test_is_available_false_with_no_key(monkeypatch):
+    monkeypatch.delenv("DEEPSEEK_API_KEY", raising=False)
+    llm = DeepSeek(api_key=None)
+    assert llm.is_available() is False
+
+
+def test_generate_raises_clear_error_when_unavailable(monkeypatch):
+    monkeypatch.delenv("DEEPSEEK_API_KEY", raising=False)
+    llm = DeepSeek(api_key=None)
+    with pytest.raises(ProcessingError, match="DeepSeek provider not available"):
+        llm.generate("hello")
+
+
+def test_generate_forwards_to_the_real_provider_when_available():
+    llm = DeepSeek(api_key="fake-key")
+    llm.provider = MagicMock()
+    llm.provider.is_available.return_value = True
+    llm.provider.generate.return_value = "a fake response"
+
+    result = llm.generate("hello", temperature=0.5)
+
+    assert result == "a fake response"
+    llm.provider.generate.assert_called_once_with("hello", temperature=0.5)
+
+
+def test_generate_structured_forwards_to_the_real_provider():
+    llm = DeepSeek(api_key="fake-key")
+    llm.provider = MagicMock()
+    llm.provider.is_available.return_value = True
+    llm.provider.generate_structured.return_value = {"key": "value"}
+
+    result = llm.generate_structured("hello")
+
+    assert result == {"key": "value"}
+    llm.provider.generate_structured.assert_called_once_with("hello")
+
+
+def test_generate_typed_forwards_schema_and_max_retries():
+    llm = DeepSeek(api_key="fake-key")
+    llm.provider = MagicMock()
+    llm.provider.is_available.return_value = True
+    fake_schema = object()
+    llm.provider.generate_typed.return_value = "typed result"
+
+    result = llm.generate_typed("hello", fake_schema, max_retries=5)
+
+    assert result == "typed result"
+    llm.provider.generate_typed.assert_called_once_with(
+        "hello", fake_schema, max_retries=5
+    )
+
+
+def test_generate_structured_raises_clear_error_when_unavailable(monkeypatch):
+    monkeypatch.delenv("DEEPSEEK_API_KEY", raising=False)
+    llm = DeepSeek(api_key=None)
+    with pytest.raises(ProcessingError, match="DeepSeek provider not available"):
+        llm.generate_structured("hello")
+
+
+def test_generate_typed_raises_clear_error_when_unavailable(monkeypatch):
+    monkeypatch.delenv("DEEPSEEK_API_KEY", raising=False)
+    llm = DeepSeek(api_key=None)
+    with pytest.raises(ProcessingError, match="DeepSeek provider not available"):
+        llm.generate_typed("hello", object())

tests/test_llm_gemini.py

@@ -0,0 +1,80 @@
+"""Tests for the Gemini LLM provider wrapper (semantica.llms.Gemini)."""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from semantica.llms import Gemini
+from semantica.utils.exceptions import ProcessingError
+
+
+def test_construction_stores_model_and_api_key():
+    gemini = Gemini(model="gemini-pro", api_key="fake-key")
+    assert gemini.model == "gemini-pro"
+    assert gemini.api_key == "fake-key"
+
+
+def test_is_available_false_with_no_key(monkeypatch):
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    gemini = Gemini(api_key=None)
+    assert gemini.is_available() is False
+
+
+def test_generate_raises_clear_error_when_unavailable(monkeypatch):
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    gemini = Gemini(api_key=None)
+    with pytest.raises(ProcessingError, match="Gemini provider not available"):
+        gemini.generate("hello")
+
+
+def test_generate_forwards_to_the_real_provider_when_available():
+    gemini = Gemini(api_key="fake-key")
+    gemini.provider = MagicMock()
+    gemini.provider.is_available.return_value = True
+    gemini.provider.generate.return_value = "a fake response"
+
+    result = gemini.generate("hello", temperature=0.5)
+
+    assert result == "a fake response"
+    gemini.provider.generate.assert_called_once_with("hello", temperature=0.5)
+
+
+def test_generate_structured_forwards_to_the_real_provider():
+    gemini = Gemini(api_key="fake-key")
+    gemini.provider = MagicMock()
+    gemini.provider.is_available.return_value = True
+    gemini.provider.generate_structured.return_value = {"key": "value"}
+
+    result = gemini.generate_structured("hello")
+
+    assert result == {"key": "value"}
+    gemini.provider.generate_structured.assert_called_once_with("hello")
+
+
+def test_generate_typed_forwards_schema_and_max_retries():
+    gemini = Gemini(api_key="fake-key")
+    gemini.provider = MagicMock()
+    gemini.provider.is_available.return_value = True
+    fake_schema = object()
+    gemini.provider.generate_typed.return_value = "typed result"
+
+    result = gemini.generate_typed("hello", fake_schema, max_retries=5)
+
+    assert result == "typed result"
+    gemini.provider.generate_typed.assert_called_once_with(
+        "hello", fake_schema, max_retries=5
+    )
+
+
+def test_generate_structured_raises_clear_error_when_unavailable(monkeypatch):
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    gemini = Gemini(api_key=None)
+    with pytest.raises(ProcessingError, match="Gemini provider not available"):
+        gemini.generate_structured("hello")
+
+
+def test_generate_typed_raises_clear_error_when_unavailable(monkeypatch):
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+    gemini = Gemini(api_key=None)
+    with pytest.raises(ProcessingError, match="Gemini provider not available"):
+        gemini.generate_typed("hello", object())

tests/test_llm_novita.py

@@ -0,0 +1,80 @@
+"""Tests for the Novita LLM provider wrapper (semantica.llms.Novita)."""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from semantica.llms import Novita
+from semantica.utils.exceptions import ProcessingError
+
+
+def test_construction_stores_model_and_api_key():
+    llm = Novita(model="deepseek/deepseek-v3.2", api_key="fake-key")
+    assert llm.model == "deepseek/deepseek-v3.2"
+    assert llm.api_key == "fake-key"
+
+
+def test_is_available_false_with_no_key(monkeypatch):
+    monkeypatch.delenv("NOVITA_API_KEY", raising=False)
+    llm = Novita(api_key=None)
+    assert llm.is_available() is False
+
+
+def test_generate_raises_clear_error_when_unavailable(monkeypatch):
+    monkeypatch.delenv("NOVITA_API_KEY", raising=False)
+    llm = Novita(api_key=None)
+    with pytest.raises(ProcessingError, match="Novita provider not available"):
+        llm.generate("hello")
+
+
+def test_generate_forwards_to_the_real_provider_when_available():
+    llm = Novita(api_key="fake-key")
+    llm.provider = MagicMock()
+    llm.provider.is_available.return_value = True
+    llm.provider.generate.return_value = "a fake response"
+
+    result = llm.generate("hello", temperature=0.5)
+
+    assert result == "a fake response"
+    llm.provider.generate.assert_called_once_with("hello", temperature=0.5)
+
+
+def test_generate_structured_forwards_to_the_real_provider():
+    llm = Novita(api_key="fake-key")
+    llm.provider = MagicMock()
+    llm.provider.is_available.return_value = True
+    llm.provider.generate_structured.return_value = {"key": "value"}
+
+    result = llm.generate_structured("hello")
+
+    assert result == {"key": "value"}
+    llm.provider.generate_structured.assert_called_once_with("hello")
+
+
+def test_generate_typed_forwards_schema_and_max_retries():
+    llm = Novita(api_key="fake-key")
+    llm.provider = MagicMock()
+    llm.provider.is_available.return_value = True
+    fake_schema = object()
+    llm.provider.generate_typed.return_value = "typed result"
+
+    result = llm.generate_typed("hello", fake_schema, max_retries=5)
+
+    assert result == "typed result"
+    llm.provider.generate_typed.assert_called_once_with(
+        "hello", fake_schema, max_retries=5
+    )
+
+
+def test_generate_structured_raises_clear_error_when_unavailable(monkeypatch):
+    monkeypatch.delenv("NOVITA_API_KEY", raising=False)
+    llm = Novita(api_key=None)
+    with pytest.raises(ProcessingError, match="Novita provider not available"):
+        llm.generate_structured("hello")
+
+
+def test_generate_typed_raises_clear_error_when_unavailable(monkeypatch):
+    monkeypatch.delenv("NOVITA_API_KEY", raising=False)
+    llm = Novita(api_key=None)
+    with pytest.raises(ProcessingError, match="Novita provider not available"):
+        llm.generate_typed("hello", object())

tests/test_llm_ollama.py

@@ -0,0 +1,78 @@
+"""Tests for the Ollama LLM provider wrapper (semantica.llms.Ollama)."""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from semantica.llms import Ollama
+from semantica.utils.exceptions import ProcessingError
+
+
+def test_construction_stores_model_and_base_url():
+    llm = Ollama(model="llama2", base_url="http://localhost:11434")
+    assert llm.model == "llama2"
+    assert llm.base_url == "http://localhost:11434"
+
+
+def test_is_available_false_without_a_running_server():
+    """No api_key here, Ollama has none. Without a real server (or the ollama
+    package) reachable at base_url, this must be a real False."""
+    llm = Ollama(base_url="http://localhost:1")
+    assert llm.is_available() is False
+
+
+def test_generate_raises_clear_error_when_unavailable():
+    llm = Ollama(base_url="http://localhost:1")
+    with pytest.raises(ProcessingError, match="Ollama provider not available"):
+        llm.generate("hello")
+
+
+def test_generate_forwards_to_the_real_provider_when_available():
+    llm = Ollama()
+    llm.provider = MagicMock()
+    llm.provider.is_available.return_value = True
+    llm.provider.generate.return_value = "a fake response"
+
+    result = llm.generate("hello", temperature=0.5)
+
+    assert result == "a fake response"
+    llm.provider.generate.assert_called_once_with("hello", temperature=0.5)
+
+
+def test_generate_structured_forwards_to_the_real_provider():
+    llm = Ollama()
+    llm.provider = MagicMock()
+    llm.provider.is_available.return_value = True
+    llm.provider.generate_structured.return_value = {"key": "value"}
+
+    result = llm.generate_structured("hello")
+
+    assert result == {"key": "value"}
+    llm.provider.generate_structured.assert_called_once_with("hello")
+
+
+def test_generate_typed_forwards_schema_and_max_retries():
+    llm = Ollama()
+    llm.provider = MagicMock()
+    llm.provider.is_available.return_value = True
+    fake_schema = object()
+    llm.provider.generate_typed.return_value = "typed result"
+
+    result = llm.generate_typed("hello", fake_schema, max_retries=5)
+
+    assert result == "typed result"
+    llm.provider.generate_typed.assert_called_once_with(
+        "hello", fake_schema, max_retries=5
+    )
+
+
+def test_generate_structured_raises_clear_error_when_unavailable():
+    llm = Ollama(base_url="http://localhost:1")
+    with pytest.raises(ProcessingError, match="Ollama provider not available"):
+        llm.generate_structured("hello")
+
+
+def test_generate_typed_raises_clear_error_when_unavailable():
+    llm = Ollama(base_url="http://localhost:1")
+    with pytest.raises(ProcessingError, match="Ollama provider not available"):
+        llm.generate_typed("hello", object())