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

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 implements the OpenAI provider, while 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 under [project.optional-dependencies]. To add LLM support, install the specific extra corresponding to your provider.

# 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
• Anthropic: semantica/llms/anthropic.py
• Groq: Fast inference via semantica/llms/groq.py
• Local models: Ollama support via semantica/llms/ollama.py

Integrating LLMs into Extraction Workflows

Entity Extraction with OpenAI

The extract_entities_llm() function in 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.

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.

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.

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 ensures graceful failures. If you attempt to use a provider without installing its extra, the system raises MissingOptionalDependencyError with installation instructions.

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. This function uses safe_import() from 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 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 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, 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, 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 and HuggingFace models. Install via pip install "semantica[llm-ollama]" to run extraction workflows entirely on local hardware without external API dependencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}