# How to Integrate LLMs with Semantica's Optional Modules: A Complete Guide

> Integrate LLMs with Semantica seamlessly. Install LLM extras and use AI-powered extraction for entities and relations. Enhance your core installation without bloat.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-12

---

**Install the specific LLM extra (e.g., `pip install "semantica[llm-openai]"`), import the extraction functions from `semantica.semantic_extract.methods`, and pass the provider name to methods like `extract_entities_llm()` to enable AI-powered entity and relation extraction without bloating your core installation.**

Semantica is an open-source semantic framework designed with a lightweight core and pluggable, optional capabilities. When you need to integrate Large Language Models (LLMs) for advanced extraction tasks, Semantica's optional modules provide a clean, dependency-isolated approach. This guide demonstrates how to leverage these optional LLM integrations using the actual source implementation from the semantica-agi/semantica repository.

## Understanding Semantica's Modular LLM Architecture

### The Core vs. Optional Modules Design

The semantica-agi/semantica repository separates its foundational graph operations from AI-powered features. The core package contains the data model and ingestion pipelines, while LLM capabilities reside in `semantica/llms/` as optional modules. This design ensures that users who only need structural graph features can avoid heavy dependencies like the OpenAI or Anthropic SDKs.

### Provider Implementation Structure

Each LLM provider inherits from `LLMBase` in the optional modules. For example, [`semantica/llms/openai.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/llms/openai.py) implements the OpenAI provider, while [`semantica/llms/anthropic.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/llms/anthropic.py) handles Claude models. These classes expose standardized `generate()` and `generate_typed()` methods that the extraction layer consumes according to the base interface.

## Installing LLM Optional Dependencies

Optional dependencies are declared in [`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml) under `[project.optional-dependencies]`. To add LLM support, install the specific extra corresponding to your provider.

```bash

# OpenAI integration

pip install "semantica[llm-openai]"

# Anthropic integration

pip install "semantica[llm-anthropic]"

# Alternative providers

pip install "semantica[llm-groq]"
pip install "semantica[llm-gemini]"
pip install "semantica[llm-ollama]"

```

### Supported LLM Providers

The repository supports multiple providers through dedicated modules in `semantica/llms/`:

- **OpenAI**: [`semantica/llms/openai.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/llms/openai.py)
- **Anthropic**: [`semantica/llms/anthropic.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/llms/anthropic.py)
- **Groq**: Fast inference via [`semantica/llms/groq.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/llms/groq.py)
- **Local models**: Ollama support via [`semantica/llms/ollama.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/llms/ollama.py)

## Integrating LLMs into Extraction Workflows

### Entity Extraction with OpenAI

The `extract_entities_llm()` function in [`semantica/semantic_extract/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/methods.py) accepts a provider string and model configuration. When you specify `provider="openai"`, the function internally calls `create_provider()` to instantiate the OpenAI class from the optional module.

```python
from semantica.semantic_extract.methods import extract_entities_llm

text = "Apple Inc. announced new AI features in Cupertino."

entities = extract_entities_llm(
    text,
    provider="openai",
    model="gpt-4o-mini",
    temperature=0.0,
    max_tokens=500
)

for entity in entities:
    print(f"{entity.text}: {entity.label}")

```

### Relation Extraction with Anthropic

Similarly, `extract_relations_llm()` enables relationship identification using Claude models. The function signature remains consistent across providers, allowing you to switch from OpenAI to Anthropic by changing the provider parameter.

```python
from semantica.semantic_extract.methods import extract_relations_llm

relations = extract_relations_llm(
    text,
    provider="anthropic",
    model="claude-3-5-sonnet-20240620",
    max_tokens=800
)

for rel in relations:
    print(f"{rel.subject} --{rel.predicate}--> {rel.object}")

```

### Advanced Pipeline Integration

For complex workflows, the `DecisionPipeline` accepts LLM configuration parameters to automatically route extraction tasks through your chosen provider.

```python
from semantica.context.decision_pipeline import DecisionPipeline

pipeline = DecisionPipeline(
    llm_provider="openai",
    llm_model="gpt-4o",
    # Additional components like vector stores can be configured here

)

results = pipeline.run(text)

```

### Handling Missing Dependencies

The `safe_import()` utility in [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py) ensures graceful failures. If you attempt to use a provider without installing its extra, the system raises `MissingOptionalDependencyError` with installation instructions.

```python
from semantica.semantic_extract.methods import extract_entities_llm
from semantica.utils.exceptions import MissingOptionalDependencyError

try:
    entities = extract_entities_llm(text, provider="groq")
except MissingOptionalDependencyError as e:
    print(f"Missing dependency: {e}")
    # Fallback to rule-based extraction

    from semantica.semantic_extract.methods import extract_entities_rule_based
    entities = extract_entities_rule_based(text)

```

## How Optional Module Loading Works Internally

The integration relies on lazy loading through the `create_provider()` factory function in [`semantica/semantic_extract/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/methods.py). This function uses `safe_import()` from [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py) to attempt importing the requested provider module only when needed. If the import succeeds, the provider class is instantiated; if it fails, users receive a targeted error message indicating which `pip install "semantica[llm-xxx]"` command to run.

This architecture provides several benefits:

- **Reduced footprint**: Core installations remain lightweight
- **Version isolation**: Different projects can pin specific provider SDK versions
- **Runtime flexibility**: Switch providers by changing a string parameter without code refactoring

## Summary

- Install specific LLM extras using `pip install "semantica[llm-<provider>]"` to avoid unnecessary dependencies
- Use `extract_entities_llm()`, `extract_relations_llm()`, and `extract_triplets_llm()` from [`semantica/semantic_extract/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/methods.py) with the `provider` parameter to specify your LLM backend
- Provider implementations in `semantica/llms/` inherit from `LLMBase` and expose standardized `generate()` methods
- The `safe_import()` mechanism in [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py) ensures clear error messages when optional dependencies are missing
- `DecisionPipeline` seamlessly integrates LLM extraction into complex workflows through configuration parameters

## Frequently Asked Questions

### What happens if I try to use an LLM provider without installing the optional dependency?

The system raises a `MissingOptionalDependencyError` that includes the specific pip install command needed (e.g., `pip install "semantica[llm-openai]"`). This error originates from the `safe_import()` helper in [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py), which checks for module availability before attempting instantiation.

### Can I switch between different LLM providers without changing my extraction code?

Yes. The `extract_entities_llm()` and related functions accept a `provider` string parameter. You can switch from OpenAI to Anthropic by changing `provider="openai"` to `provider="anthropic"` and ensuring the corresponding extra is installed, without modifying any other logic in your application.

### Does Semantica cache LLM responses to reduce API costs?

Yes. According to the implementation in [`semantica/semantic_extract/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/methods.py), the extraction methods cache results based on the exact prompt and LLM parameters including `max_tokens` and temperature settings. Modifying any parameter generates a new cache key, ensuring you can control when fresh API calls occur while avoiding redundant requests for identical inputs.

### Are local LLMs supported through the optional modules?

Yes. The optional module system includes support for local inference via Ollama in [`semantica/llms/ollama.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/llms/ollama.py) and HuggingFace models. Install via `pip install "semantica[llm-ollama]"` to run extraction workflows entirely on local hardware without external API dependencies.