Generate knowledge graphs with natural language.
Run unit tests.
deno task testFormat and lint code.
deno task precommitTurtle agent converts natural language into RDF knowledge graphs using a multi-stage pipeline.
- Uses Google Gemini 2.5 Flash to generate Turtle RDF from natural language
- Extracts entities with placeholder IDs from the generated Turtle
- Validates output against SHACL shapes with automatic retry (up to 3 attempts)
- Uses few-shot examples and conversation history for context
- Searches existing knowledge graph for matching entities
- Disambiguates multiple candidates when found
- Substitutes placeholder IDs with resolved entity URIs
- Indexes RDF triples in Orama for fast entity lookup
- Searches object literals to find matching subjects
- Returns ranked candidates by relevance score
PromptDisambiguationService(default): Interactive CLI prompts for entity selectionGreedyDisambiguator(fast mode): Automatically selects highest-scoring candidate
N3Store: Primary RDF storage using N3.js, persisted to_db.ttlfiles- Orama: Hybrid vector and full-text search index, persisted to
_orama.jsonfiles OramaSyncInterceptor: Automatically keeps Orama in sync with N3Store operations- Automerge: Automerge is planned as a future enhancement.
User Input (Natural Language)
↓
TurtleGenerator.generate()
├─→ LLM (Gemini) generates Turtle RDF with placeholder IDs
├─→ SHACL validation (with retry on failure)
└─→ Entity extraction (variables with placeholders)
↓
EntityLinker.linkEntities()
├─→ For each entity:
│ ├─→ OramaSearchService.search() → Find candidates
│ └─→ Disambiguator.disambiguate() → Resolve to URI
└─→ Substitute placeholders with resolved URIs
↓
insertTurtle() → N3Store
↓
OramaSyncInterceptor → Automatically syncs to Orama
↓
Persist to disk (_db.ttl + _orama.json)
USER> Ethan farted 5 times today
Generating Turtle...
'farted 5 times' - Enter ID (leave blank to generate a random ID)
'Ethan' - Enter ID (leave blank to generate a random ID)
'farts' - Enter ID (leave blank to generate a random ID)
Added generated Turtle to N3 store. Total triples: 10
USER> Ethan wears a green shirt.
Generating Turtle...
'wears a green shirt' - Enter ID (leave blank to generate a random ID)
'Ethan' - Select the associated entity
❯ 3.40 - <https://fartlabs.org/.well-known/genid/01KADC78P479D5NG1T61QVX9E6>
'green shirt' - Enter ID (leave blank to generate a random ID)
Added generated Turtle to N3 store. Total triples: 17
Below is a simplified illustration of the triples generated in the session above so you can see how entities relate inside the generated knowledge graph.
+--------------------------------+
| ID: 01KADC78P479D5NG1T61QVX9E6 |
| Type: schema:Person |
| Name: "Ethan" |
+--------------------------------+
|
|
+---------------+---------------+
| |
| (schema:agent) | (schema:agent)
+---------------------------------+ +---------------------------------+
| ID: 01KADC7806MRH9PJTJ8X1WCC8B | | ID: 01KADC86PFF61YFGX07WMEV2DX |
| Type: schema:PerformAction | | Type: schema:WearAction |
| Status: schema:CompletedAction | | Status: schema:ActiveAction |
| Name: "Farted 5 times" | | Name: "Green shirt" |
+---------------------------------+ +---------------------------------+
The system learns from previous interactions. When "Ethan" is mentioned again, it references the existing entity and prompts for confirmation.
Developed with 💖 @FartLabs