How do I install the Service Guide skill?

Run npx skillmds@latest add tomevault-io/service-guide in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Service Guide skill do?

Overview of the service layer architecture and usage Use when this capability is needed. It is listed under Coding & Dev Tools on SkillMD.

Is Service Guide safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Service Guide?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Service Guide free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Service Guide?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Service Guide by tomevault-io — Agent Skill

Name: Service Guide
Author: tomevault-io

File contents

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

Document ingestion - Bulk insert with metadata
Annotation ingestion - Add entity occurrences first, then triplets/tuplets
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 — claim your Tome and manage your conversions.

---name: service-guidedescription: Overview of the service layer architecture and usage Use when this capability is needed.---# Service Layer GuideOverview 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.## QueryServiceComposes 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 operationsAll sub-services provide: DataFrame export, single/multiple record retrieval, plus entity-specific queries.## PopulationService1. **Document ingestion** - Bulk insert with metadata2. **Annotation ingestion** - Add entity occurrences first, then triplets/tuplets3. **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.

Frequently asked questions

Service Guide