PlanOpticon builds structured knowledge graphs from video analyses, document ingestion, and other content sources. A knowledge graph captures **entities** (people, technologies, concepts, organizations) and the **relationships** between them, providing a queryable representation of everything discussed or presented in your source material.
4
5
---
6
7
## Storage
8
9
Knowledge graphs are stored as SQLite databases (`knowledge_graph.db`) using Python's built-in `sqlite3` module. This means:
10
11
- **Zero external dependencies.** No database server to install or manage.
12
- **Single-file portability.** Copy the `.db` file to share a knowledge graph.
13
- **WAL mode.** SQLite Write-Ahead Logging is enabled for concurrent read performance.
14
- **JSON fallback.** Knowledge graphs can also be saved as `knowledge_graph.json` for interoperability, though SQLite is preferred for performance and querying.
15
16
### Database Schema
17
18
The SQLite store uses the following tables:
19
20
| Table | Purpose |
21
|---|---|
22
| `entities` | Core entity records with name, type, descriptions, source, and arbitrary properties |
23
| `occurrences` | Where and when each entity was mentioned (source, timestamp, text snippet) |
24
| `relationships` | Directed edges between entities with type, content source, timestamp, and properties |
| `source_locations` | Links between sources and specific entities/relationships, with location details (timestamp, page, section, line range, text snippet) |
27
28
All entity lookups are case-insensitive (indexed on `name_lower`). Entities and relationships are indexed on their source and target fields for efficient traversal.
29
30
### Storage Backends
31
32
PlanOpticon supports two storage backends, selected automatically:
33
34
| Backend | When Used | Persistence |
35
|---|---|---|
36
| `SQLiteStore` | When a `db_path` is provided | Persistent on disk |
37
| `InMemoryStore` | When no path is given, or as fallback | In-memory only |
38
39
Both backends implement the same `GraphStore` abstract interface, so all query and manipulation code works identically regardless of backend.
40
41
```python
42
from video_processor.integrators.graph_store import create_store
43
44
# Persistent SQLite store
45
store = create_store("/path/to/knowledge_graph.db")
46
47
# In-memory store (for temporary operations)
48
store = create_store()
49
```
50
51
---
52
53
## Entity Types
54
55
Entities extracted from content are assigned one of the following base types:
56
57
| Type | Description | Specificity Rank |
58
|---|---|---|
59
| `person` | People mentioned or participating | 3 (highest) |
The specificity rank is used during merge operations: when two entities are matched as duplicates, the more specific type wins (e.g., `technology` overrides `concept`).
67
68
### Planning Taxonomy
69
70
Beyond the base entity types, PlanOpticon includes a planning taxonomy for classifying entities into project-planning categories. The `TaxonomyClassifier` maps extracted entities into these types:
71
72
| Planning Type | Keywords Matched |
73
|---|---|
74
| `goal` | goal, objective, aim, target outcome |
75
| `requirement` | must, should, requirement, need, required |
76
| `constraint` | constraint, limitation, restrict, cannot, must not |
1. **Heuristic classification.** Entity descriptions are scanned for the keywords listed above. First match wins.
88
2. **LLM refinement.** If an LLM provider is available, entities are sent to the LLM for more nuanced classification with priority assignment (`high`, `medium`, `low`). LLM results override heuristic results on conflicts.
89
90
Classified entities are used by planning agent skills (project_plan, prd, roadmap, task_breakdown) to produce targeted, context-aware artifacts.
91
92
---
93
94
## Relationship Types
95
96
Relationships are directed edges between entities. The `type` field is a free-text string determined by the LLM during extraction. Common relationship types include:
97
98
- `related_to` (default)
99
- `works_with`
100
- `uses`
101
- `depends_on`
102
- `proposed`
103
- `discussed_by`
104
- `employed_by`
105
- `collaborates_with`
106
- `expert_in`
107
108
### Typed Relationships
109
110
The `add_typed_relationship()` method creates edges with custom labels and optional properties, enabling richer graph semantics:
The primary path for building a knowledge graph is through video analysis. When you run `planopticon analyze`, the pipeline extracts entities and relationships from:
140
141
- **Transcript segments** -- batched in groups of 10 for efficient API usage, with speaker identification
142
- **Diagram content** -- text extracted from visual diagrams detected in video frames
143
144
```bash
145
planopticon analyze -i meeting.mp4 -o results/
146
# Creates results/knowledge_graph.db
147
```
148
149
### From Document Ingestion
150
151
Documents (Markdown, PDF, DOCX) can be ingested directly into a knowledge graph:
When combining knowledge graphs from multiple sources, PlanOpticon performs intelligent merge with deduplication.
204
205
### Fuzzy Name Matching
206
207
Entity names are compared using Python's `SequenceMatcher` with a threshold of 0.85. This means "Kubernetes" and "kubernetes" are matched exactly (case-insensitive), while "React.js" and "ReactJS" may be matched as duplicates if their similarity ratio meets the threshold.
208
209
### Type Conflict Resolution
210
211
When two entities match but have different types, the more specific type wins based on the specificity ranking:
Get all source locations for a specific entity, showing exactly where it was mentioned:
324
325
```python
326
engine.provenance("Kubernetes")
327
# Returns source locations with timestamps, pages, sections, and text snippets
328
```
329
330
#### Raw SQL
331
332
Execute arbitrary SQL against the SQLite backend (SQLite stores only):
333
334
```python
335
engine.sql("SELECT name, type FROM entities WHERE type = 'technology' ORDER BY name")
336
```
337
338
### Agentic Mode
339
340
Agentic mode accepts natural-language questions and uses the LLM to plan and execute queries. It requires a configured LLM provider.
341
342
```bash
343
planopticon query "What technologies were discussed?"
344
planopticon query "Who are the key people mentioned?"
345
planopticon query "What depends on the authentication service?"
346
```
347
348
The agentic query pipeline:
349
350
1. **Plan.** The LLM receives graph stats and available actions (entities, relationships, neighbors, stats). It selects exactly one action and its parameters.
351
2. **Execute.** The chosen action is run through the direct-mode engine.
352
3. **Synthesize.** The LLM receives the raw query results and the original question, then produces a concise natural-language answer.
353
354
This design ensures the LLM never generates arbitrary code -- it only selects from a fixed set of known query actions.
355
356
```bash
357
# Requires an API key
358
planopticon query "What technologies were discussed?" -p openai
359
360
# Use the interactive REPL for multiple queries
361
planopticon query -I
362
```
363
364
---
365
366
## Graph Query Engine Python API
367
368
The `GraphQueryEngine` class provides the programmatic interface for all query operations.
369
370
### Initialization
371
372
```python
373
from video_processor.integrators.graph_query import GraphQueryEngine
374
from video_processor.integrators.graph_discovery import find_nearest_graph
PlanOpticon includes a zero-dependency HTML knowledge graph viewer at `knowledge-base/viewer.html`. This file is fully self-contained -- it inlines D3.js and requires no build step, no server, and no internet connection.
421
422
To use it, open `viewer.html` in a browser. It will load and visualize a `knowledge_graph.json` file (place it in the same directory, or use the file picker in the viewer).
423
424
The viewer provides:
425
426
- Interactive force-directed graph layout
427
- Zoom and pan navigation
428
- Entity nodes colored by type
429
- Relationship edges with labels
430
- Click-to-focus on individual entities
431
- Entity detail panel showing descriptions and connections
432
433
This covers approximately 80% of graph exploration needs with zero infrastructure.
434
435
---
436
437
## KG Management Commands
438
439
The `planopticon kg` command group provides utilities for managing knowledge graph files.
440
441
### kg convert
442
443
Convert a knowledge graph between SQLite and JSON formats:
444
445
```bash
446
# SQLite to JSON
447
planopticon kg convert results/knowledge_graph.db output.json
448
449
# JSON to SQLite
450
planopticon kg convert knowledge_graph.json knowledge_graph.db
451
```
452
453
The output format is inferred from the destination file extension. Source and destination must be different formats.
454
455
### kg sync
456
457
Synchronize a `.db` and `.json` knowledge graph, updating the stale one:
458
459
```bash
460
# Auto-detect which is newer and sync
461
planopticon kg sync results/knowledge_graph.db
462
463
# Explicit JSON path
464
planopticon kg sync knowledge_graph.db knowledge_graph.json
465
466
# Force a specific direction
467
planopticon kg sync knowledge_graph.db knowledge_graph.json --direction db-to-json
468
planopticon kg sync knowledge_graph.db knowledge_graph.json --direction json-to-db
469
```
470
471
If `JSON_PATH` is omitted, the `.json` path is derived from the `.db` path (same name, different extension). In `auto` mode (the default), the newer file is used as the source.
472
473
### kg inspect
474
475
Show summary statistics for a knowledge graph file:
476
477
```bash
478
planopticon kg inspect results/knowledge_graph.db
479
```
480
481
Output:
482
483
```
484
File: results/knowledge_graph.db
485
Store: sqlite
486
Entities: 42
487
Relationships: 87
488
Entity types:
489
technology: 15
490
person: 12
491
concept: 10
492
organization: 5
493
```
494
495
Works with both `.db` and `.json` files.
496
497
### kg classify
498
499
Classify knowledge graph entities into planning taxonomy types:
500
501
```bash
502
# Heuristic + LLM classification
503
planopticon kg classify results/knowledge_graph.db
504
505
# Heuristic only (no API key needed)
506
planopticon kg classify results/knowledge_graph.db -p none
507
508
# JSON output
509
planopticon kg classify results/knowledge_graph.db --format json
510
```
511
512
Text output groups entities by planning type:
513
514
```
515
GOALS (3)
516
- Improve system reliability [high]
517
Must achieve 99.9% uptime
518
- Reduce deployment time [medium]
519
Automate the deployment pipeline
520
521
RISKS (2)
522
- Data migration complexity [high]
523
Legacy schema incompatibilities
524
...
525
526
TASKS (5)
527
- Implement OAuth2 flow
528
Set up authentication service
529
...
530
```
531
532
JSON output returns an array of `PlanningEntity` objects with `name`, `planning_type`, `priority`, `description`, and `source_entities` fields.
533
534
### kg from-exchange
535
536
Import a PlanOpticonExchange JSON file into a knowledge graph database:
537
538
```bash
539
# Import to default location (./knowledge_graph.db)
540
planopticon kg from-exchange exchange.json
541
542
# Import to a specific path
543
planopticon kg from-exchange exchange.json -o project.db
544
```
545
546
The PlanOpticonExchange format is a standardized interchange format that includes entities, relationships, and source records.
547
548
---
549
550
## Output Formats
551
552
Query results can be output in three formats:
553
554
### Text (default)
555
556
Human-readable format with entity types in brackets, relationship arrows, and indented details:
557
558
```
559
Found 15 entities
560
[technology] Python -- General-purpose programming language