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

> Learn semantic extraction with Semantica. Perform NER, relation, and event detection using a unified pipeline. Discover extract_entities, extract_relations, and extract_all.

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

---

**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`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/schemas.py) |
| **Tool handlers** | Orchestrates low-level extractors and cache management | [`semantica/mcp/tools/extraction.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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

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

```

### Extract Relations and Triples

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

```

### Full Pipeline with Coreference

```bash
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`:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp_server/__main__.py):

```bash
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/extraction.py) | Handler implementations and `EXTRACTION_TOOLS` registry |
| [`semantica/mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/schemas.py) | JSON schemas: `EXTRACT_ENTITIES`, `EXTRACT_RELATIONS`, `EXTRACT_ALL` |
| [`semantica/mcp_server/__main__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp_server/__main__.py) | HTTP server entry point for remote tool access |
| [`semantica/semantic_extract/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/__init__.py) | Core extractor class exports |

The `_clear_cache()` function in [`semantica/mcp/tools/extraction.py`](https://github.com/semantica-agi/semantica/blob/main/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.