# Service Guide

> Overview of the service layer architecture and usage Use when this capability is needed.

- Skill: `tomevault-io/service-guide` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/service-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/service-guide/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/service-guide

---


# Service Layer Guide

Overview of the service layer in `narrativegraphs/service/`.

## Core Services

| Service               | Purpose                                                       |
| --------------------- | ------------------------------------------------------------- |
| **QueryService**      | Read/query operations (documents, entities, relations, graph) |
| **PopulationService** | Write operations (adding docs, annotations, mapping)          |

Both extend `DbService` which provides thread-safe session management.

## QueryService

Composes sub-services for each entity type:

- `documents` - DocService for DocumentOrm
- `entities` - EntityService for EntityOrm (includes search)
- `relations` - RelationService for RelationOrm
- `predicates` - PredicateService for PredicateOrm
- `cooccurrences` - CooccurrenceService for CooccurrenceOrm
- `triplets` - TripletService for TripletOrm
- `tuplets` - TupletService for TupletOrm
- `graph` - GraphService for graph operations

All sub-services provide: DataFrame export, single/multiple record retrieval, plus entity-specific queries.

## PopulationService

1. **Document ingestion** - Bulk insert with metadata
2. **Annotation ingestion** - Add entity occurrences first, then triplets/tuplets
3. **Mapping** - Map annotations to canonical entities/predicates/relations/cooccurrences

## Supporting Services

### StatsCalculator (`stats.py`)

Computes aggregate statistics after population: frequency, doc_frequency, spread, TF-IDF, timestamps, relation significance, cooccurrence PMI, category propagation.

### GraphService (`graph.py`)

Graph operations: subgraph extraction, expansion from focus entities, community detection (louvain, k_clique, connected_components). Supports `"relation"` and `"cooccurrence"` connection types.

### Caches (`cache.py`)

Used by PopulationService for efficient bulk mapping: EntityCache, PredicateCache, CooccurrenceCache, RelationCache.

### Filter Functions (`filter.py`)

Builds SQLAlchemy conditions for graph queries: date range, frequency bounds, categories, blacklist.

## Architecture

```
QueryService (read)                    PopulationService (write)
    │                                          │
    ├── sub-services per entity type           ├── add documents/annotations
    └── graph (GraphService)                   └── map to canonical (uses Caches)
            │
            └── filter.py conditions

                    StatsCalculator.calculate_stats() after population
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kasperfyhn) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->