How to Perform Semantic Extraction in Semantica: NER, Relations, and Event Detection

Semantica provides a unified MCP-based pipeline for Named Entity Recognition (NER), relation extraction, and event detection through three core tools: extract_entities, extract_relations, and extract_all.

Semantic extraction transforms unstructured text into structured knowledge—entities, relationships, and events—that powers downstream AI systems. The semantica-agi/semantica repository implements this through a clean Machine-Control-Protocol (MCP) architecture that exposes extraction capabilities via CLI, Python API, and HTTP server.

Understanding the Semantic Extraction Architecture

Semantica organizes semantic extraction into three architectural layers:

Layer	Responsibility	Key Location
Input validation	JSON schema enforcement for tool calls	semantica/mcp/schemas.py
Tool handlers	Orchestrates low-level extractors and cache management	semantica/mcp/tools/extraction.py
Core extractors	Language models and algorithms for NER, relations, events	semantica/semantic_extract/

The MCP tool registry (EXTRACTION_TOOLS) in semantica/mcp/tools/extraction.py binds handlers to callable tools. Each handler follows a standard flow: clear cache, load extractor, run inference, normalize results to JSON-serializable dictionaries.

The Three Extraction Tools

Semantica exposes three MCP tools for different extraction scenarios:

extract_entities: Named Entity Recognition Only

Runs NER without additional processing. Input schema EXTRACT_ENTITIES requires only a text field.

Example output structure:

• entities: List of objects with label, type, start, end, confidence
• count: Total entity count

extract_relations: NER + Relation + Triple Extraction

Chains three operations: NER → RelationExtractor → TripletExtractor. Uses schema EXTRACT_RELATIONS.

Returns:

• relations: Source-target-type-confidence quadruples
• triplets: Subject-predicate-object structures
• relation_count, triplet_count: Aggregation fields

extract_all: Full Pipeline with Coreference Resolution

The comprehensive option. Uses schema EXTRACT_ALL with optional flags include_events and include_triplets.

Executes: NER → CoreferenceResolver → RelationExtractor → EventDetector → TripletExtractor

Provides a summary object with counts across all extraction types.

Core Extractor Classes in semantica.semantic_extract

The underlying implementations share a common interface: extract(...) returning typed result objects.

Class	Purpose	Signature
NamedEntityRecognizer	Detect and classify named entities	extract(text) → List[Entity]
CoreferenceResolver	Resolve pronouns to antecedents	resolve(text) → ResolvedText
RelationExtractor	Identify semantic relationships between entities	extract(text, entities) → List[Relation]
EventDetector	Detect events and triggers	extract(text) → List[Event]
TripletExtractor	Generate subject-predicate-object triples	extract(text) → List[Triplet]

These classes are imported by semantica/mcp/tools/extraction.py and wrapped by handler functions: handle_extract_entities(), handle_extract_relations(), and handle_extract_all().

CLI Usage: semantica mcp call

The CLI exposes extraction tools through the mcp call subcommand. Results print as JSON to stdout.

Run NER Only

semantica mcp call extract_entities \
  --json '{"text": "John Smith works at Acme Corp."}'

Extract Relations and Triples

semantica mcp call extract_relations \
  --json '{"text": "John Smith bought a laptop from BestBuy."}'

Full Pipeline with Coreference

semantica mcp call extract_all \
  --json '{"text": "Alice visited Bob. She bought him a gift."}'

The --json flag accepts payloads from stdin or direct string argument. Pipe-friendly output enables integration with jq and other JSON processors.

Python API: Direct Extractor Access

For programmatic control, import extractors directly from semantica.semantic_extract:

from semantica.semantic_extract import (
    NamedEntityRecognizer,
    RelationExtractor,
    EventDetector,
    TripletExtractor,
)

text = "Alice visited Bob. She bought him a gift."

# Named Entity Recognition

ner = NamedEntityRecognizer()
entities = ner.extract(text)
print(f"Found {len(entities)} entities")

# Relations require pre-extracted entities

rel_extractor = RelationExtractor()
relations = rel_extractor.extract(text, entities)

# Event detection

event_detector = EventDetector()
events = event_detector.extract(text)

# Triple extraction

triplet_extractor = TripletExtractor()
triplets = triplet_extractor.extract(text)

# Access result attributes directly

for e in entities:
    print(f"{e.label} ({e.type}): {e.start}-{e.end}, confidence={e.confidence}")

Result objects expose attributes used by MCP handlers: label, type, start, end, confidence for entities; source, target, type for relations; subject, predicate, object for triplets.

MCP Server Deployment

For remote or service-based extraction, run the MCP server via semantica/mcp_server/__main__.py:

python -m semantica.mcp_server

This exposes all EXTRACTION_TOOLS over HTTP, enabling language-agnostic access to the extraction pipeline.

Key Implementation Files

File Path	Role
semantica/mcp/tools/extraction.py	Handler implementations and EXTRACTION_TOOLS registry
semantica/mcp/schemas.py	JSON schemas: EXTRACT_ENTITIES, EXTRACT_RELATIONS, EXTRACT_ALL
semantica/mcp_server/__main__.py	HTTP server entry point for remote tool access
semantica/semantic_extract/__init__.py	Core extractor class exports

The _clear_cache() function in semantica/mcp/tools/extraction.py ensures each extraction call starts fresh—critical for avoiding stale results in long-running processes.

Summary

• Three MCP tools cover extraction needs: extract_entities, extract_relations, extract_all
• Architecture separates concerns: schemas validate, handlers orchestrate, core extractors implement NLP logic
• CLI access via semantica mcp call --json with stdin/stdout JSON pipes
• Python API allows direct instantiation of NamedEntityRecognizer, RelationExtractor, EventDetector, TripletExtractor
• HTTP server available through semantica.mcp_server for service deployments

Frequently Asked Questions

What is the difference between extract_relations and extract_all?

extract_relations runs NER, relation extraction, and triple extraction without coreference resolution or event detection. extract_all adds coreference resolution, event detection, and optional triple inclusion via include_events and include_triplets flags. Use extract_relations for relationship-focused tasks; use extract_all for comprehensive knowledge extraction.

Can I run extractors without the MCP tool wrapper?

Yes. Import directly from semantica.semantic_extract and instantiate NamedEntityRecognizer(), RelationExtractor(), or other classes. This bypasses schema validation and cache management but requires manual handling of dependencies—RelationExtractor.extract() needs pre-computed entities, for example.

How does caching work in the extraction pipeline?

The handler functions call _clear_cache() before each extraction to prevent result contamination. The cache stores intermediate outputs during multi-stage pipelines (e.g., entities reused for relation extraction). Per-call clearing ensures deterministic, reproducible results across CLI invocations.

What output format does the CLI produce?

JSON to stdout with tool-specific structures. All tools return counts and typed arrays. extract_all includes a summary object with entity, relation, event, and triplet counts. Confidence scores are float values between 0 and 1.

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