PlanOpticon

planopticon / docs / api / models.md
Source Rendered
Blame History Raw 502 lines
1
# Models API Reference
2
3
::: video_processor.models
4
5
---
6
7
## Overview
8
9
The `video_processor.models` module defines all Pydantic data models used throughout PlanOpticon for structured output, serialization, and validation. These models represent everything from individual transcript segments to complete batch processing manifests.
10
11
All models inherit from `pydantic.BaseModel` and support JSON serialization via `.model_dump_json()` and deserialization via `.model_validate_json()`.
12
13
---
14
15
## Enumerations
16
17
### DiagramType
18
19
Types of visual content detected in video frames.
20
21
```python
22
from video_processor.models import DiagramType
23
```
24
25
| Value | Description |
26
|---|---|
27
| `flowchart` | Process flow or decision tree diagrams |
28
| `sequence` | Sequence or interaction diagrams |
29
| `architecture` | System architecture diagrams |
30
| `whiteboard` | Whiteboard drawings or sketches |
31
| `chart` | Data charts (bar, line, pie, scatter) |
32
| `table` | Tabular data |
33
| `slide` | Presentation slides |
34
| `screenshot` | Application screenshots or screen shares |
35
| `unknown` | Unclassified visual content |
36
37
### OutputFormat
38
39
Available output formats for processing results.
40
41
| Value | Description |
42
|---|---|
43
| `markdown` | Markdown text |
44
| `json` | JSON data |
45
| `html` | HTML document |
46
| `pdf` | PDF document |
47
| `svg` | SVG vector graphic |
48
| `png` | PNG raster image |
49
50
### PlanningEntityType
51
52
Classification types for entities in a planning taxonomy.
53
54
| Value | Description |
55
|---|---|
56
| `goal` | Project goals or objectives |
57
| `requirement` | Functional or non-functional requirements |
58
| `constraint` | Limitations or constraints |
59
| `decision` | Decisions made during planning |
60
| `risk` | Identified risks |
61
| `assumption` | Planning assumptions |
62
| `dependency` | External or internal dependencies |
63
| `milestone` | Project milestones |
64
| `task` | Actionable tasks |
65
| `feature` | Product features |
66
67
### PlanningRelationshipType
68
69
Relationship types within a planning taxonomy.
70
71
| Value | Description |
72
|---|---|
73
| `requires` | Entity A requires entity B |
74
| `blocked_by` | Entity A is blocked by entity B |
75
| `has_risk` | Entity A has an associated risk B |
76
| `depends_on` | Entity A depends on entity B |
77
| `addresses` | Entity A addresses entity B |
78
| `has_tradeoff` | Entity A involves a tradeoff with entity B |
79
| `delivers` | Entity A delivers entity B |
80
| `implements` | Entity A implements entity B |
81
| `parent_of` | Entity A is the parent of entity B |
82
83
---
84
85
## Protocols
86
87
### ProgressCallback
88
89
A runtime-checkable protocol for receiving pipeline progress updates. Implement this interface to integrate custom progress reporting (e.g., web UI, logging).
90
91
```python
92
from video_processor.models import ProgressCallback
93
94
class MyProgress:
95
def on_step_start(self, step: str, index: int, total: int) -> None:
96
print(f"Starting {step} ({index}/{total})")
97
98
def on_step_complete(self, step: str, index: int, total: int) -> None:
99
print(f"Completed {step} ({index}/{total})")
100
101
def on_progress(self, step: str, percent: float, message: str = "") -> None:
102
print(f"{step}: {percent:.0f}% {message}")
103
104
assert isinstance(MyProgress(), ProgressCallback) # True
105
```
106
107
**Methods:**
108
109
| Method | Parameters | Description |
110
|---|---|---|
111
| `on_step_start` | `step: str`, `index: int`, `total: int` | Called when a pipeline step begins |
112
| `on_step_complete` | `step: str`, `index: int`, `total: int` | Called when a pipeline step finishes |
113
| `on_progress` | `step: str`, `percent: float`, `message: str` | Called with incremental progress updates |
114
115
---
116
117
## Transcript Models
118
119
### TranscriptSegment
120
121
A single segment of transcribed audio with timing and optional speaker identification.
122
123
| Field | Type | Default | Description |
124
|---|---|---|---|
125
| `start` | `float` | *required* | Start time in seconds |
126
| `end` | `float` | *required* | End time in seconds |
127
| `text` | `str` | *required* | Transcribed text content |
128
| `speaker` | `Optional[str]` | `None` | Speaker identifier (e.g., "Speaker 1") |
129
| `confidence` | `Optional[float]` | `None` | Transcription confidence score (0.0 to 1.0) |
130
131
```json
132
{
133
"start": 12.5,
134
"end": 15.3,
135
"text": "We should migrate to the new API by next quarter.",
136
"speaker": "Alice",
137
"confidence": 0.95
138
}
139
```
140
141
---
142
143
## Content Extraction Models
144
145
### ActionItem
146
147
An action item extracted from transcript or diagram content.
148
149
| Field | Type | Default | Description |
150
|---|---|---|---|
151
| `action` | `str` | *required* | The action to be taken |
152
| `assignee` | `Optional[str]` | `None` | Person responsible for the action |
153
| `deadline` | `Optional[str]` | `None` | Deadline or timeframe |
154
| `priority` | `Optional[str]` | `None` | Priority level (e.g., "high", "medium", "low") |
155
| `context` | `Optional[str]` | `None` | Additional context or notes |
156
| `source` | `Optional[str]` | `None` | Where this was found: `"transcript"`, `"diagram"`, or `"both"` |
157
158
```json
159
{
160
"action": "Migrate authentication service to OAuth 2.0",
161
"assignee": "Bob",
162
"deadline": "Q2 2026",
163
"priority": "high",
164
"context": "at 245s",
165
"source": "transcript"
166
}
167
```
168
169
### KeyPoint
170
171
A key point extracted from content, optionally linked to diagrams.
172
173
| Field | Type | Default | Description |
174
|---|---|---|---|
175
| `point` | `str` | *required* | The key point text |
176
| `topic` | `Optional[str]` | `None` | Topic or category |
177
| `details` | `Optional[str]` | `None` | Supporting details |
178
| `timestamp` | `Optional[float]` | `None` | Timestamp in video (seconds) |
179
| `source` | `Optional[str]` | `None` | Where this was found |
180
| `related_diagrams` | `List[int]` | `[]` | Indices of related diagrams in the manifest |
181
182
```json
183
{
184
"point": "Team decided to use FalkorDB for graph storage",
185
"topic": "Architecture",
186
"details": "Embedded database avoids infrastructure overhead for CLI use",
187
"timestamp": 342.0,
188
"source": "transcript",
189
"related_diagrams": [0, 2]
190
}
191
```
192
193
---
194
195
## Diagram Models
196
197
### DiagramResult
198
199
Result from diagram extraction and analysis. Contains structured data extracted from visual content, along with paths to output files.
200
201
| Field | Type | Default | Description |
202
|---|---|---|---|
203
| `frame_index` | `int` | *required* | Index of the source frame |
204
| `timestamp` | `Optional[float]` | `None` | Timestamp in video (seconds) |
205
| `diagram_type` | `DiagramType` | `unknown` | Type of diagram detected |
206
| `confidence` | `float` | `0.0` | Detection confidence (0.0 to 1.0) |
207
| `description` | `Optional[str]` | `None` | Detailed description of the diagram |
208
| `text_content` | `Optional[str]` | `None` | All visible text, preserving structure |
209
| `elements` | `List[str]` | `[]` | Identified elements or components |
210
| `relationships` | `List[str]` | `[]` | Identified relationships (e.g., `"A -> B: connects"`) |
211
| `mermaid` | `Optional[str]` | `None` | Mermaid syntax representation |
212
| `chart_data` | `Optional[Dict[str, Any]]` | `None` | Extractable chart data (`labels`, `values`, `chart_type`) |
213
| `image_path` | `Optional[str]` | `None` | Relative path to original frame image |
214
| `svg_path` | `Optional[str]` | `None` | Relative path to rendered SVG |
215
| `png_path` | `Optional[str]` | `None` | Relative path to rendered PNG |
216
| `mermaid_path` | `Optional[str]` | `None` | Relative path to mermaid source file |
217
218
```json
219
{
220
"frame_index": 5,
221
"timestamp": 120.0,
222
"diagram_type": "architecture",
223
"confidence": 0.92,
224
"description": "Microservices architecture showing API gateway, auth service, and database layer",
225
"text_content": "API Gateway\nAuth Service\nUser DB\nPostgreSQL",
226
"elements": ["API Gateway", "Auth Service", "User DB", "PostgreSQL"],
227
"relationships": ["API Gateway -> Auth Service: authenticates", "Auth Service -> User DB: queries"],
228
"mermaid": "graph LR\n A[API Gateway] --> B[Auth Service]\n B --> C[User DB]",
229
"chart_data": null,
230
"image_path": "diagrams/diagram_0.jpg",
231
"svg_path": null,
232
"png_path": null,
233
"mermaid_path": "diagrams/diagram_0.mermaid"
234
}
235
```
236
237
### ScreenCapture
238
239
A screengrab fallback created when diagram extraction fails or confidence is too low for full analysis.
240
241
| Field | Type | Default | Description |
242
|---|---|---|---|
243
| `frame_index` | `int` | *required* | Index of the source frame |
244
| `timestamp` | `Optional[float]` | `None` | Timestamp in video (seconds) |
245
| `caption` | `Optional[str]` | `None` | Brief description of the content |
246
| `image_path` | `Optional[str]` | `None` | Relative path to screenshot image |
247
| `confidence` | `float` | `0.0` | Detection confidence that triggered fallback |
248
249
```json
250
{
251
"frame_index": 8,
252
"timestamp": 195.0,
253
"caption": "Code editor showing a Python function definition",
254
"image_path": "captures/capture_0.jpg",
255
"confidence": 0.45
256
}
257
```
258
259
---
260
261
## Knowledge Graph Models
262
263
### Entity
264
265
An entity in the knowledge graph, representing a person, concept, technology, or other named item extracted from content.
266
267
| Field | Type | Default | Description |
268
|---|---|---|---|
269
| `name` | `str` | *required* | Entity name |
270
| `type` | `str` | `"concept"` | Entity type: `"person"`, `"concept"`, `"technology"`, `"time"`, `"diagram"` |
271
| `descriptions` | `List[str]` | `[]` | Accumulated descriptions of this entity |
272
| `source` | `Optional[str]` | `None` | Source attribution: `"transcript"`, `"diagram"`, or `"both"` |
273
| `occurrences` | `List[Dict[str, Any]]` | `[]` | Occurrences with source, timestamp, and text context |
274
275
```json
276
{
277
"name": "FalkorDB",
278
"type": "technology",
279
"descriptions": ["Embedded graph database", "Supports Cypher queries"],
280
"source": "both",
281
"occurrences": [
282
{"source": "transcript", "timestamp": 120.0, "text": "We chose FalkorDB for graph storage"},
283
{"source": "diagram", "text": "FalkorDB Lite"}
284
]
285
}
286
```
287
288
### Relationship
289
290
A directed relationship between two entities in the knowledge graph.
291
292
| Field | Type | Default | Description |
293
|---|---|---|---|
294
| `source` | `str` | *required* | Source entity name |
295
| `target` | `str` | *required* | Target entity name |
296
| `type` | `str` | `"related_to"` | Relationship type (e.g., `"uses"`, `"manages"`, `"related_to"`) |
297
| `content_source` | `Optional[str]` | `None` | Content source identifier |
298
| `timestamp` | `Optional[float]` | `None` | Timestamp in seconds |
299
300
```json
301
{
302
"source": "PlanOpticon",
303
"target": "FalkorDB",
304
"type": "uses",
305
"content_source": "transcript",
306
"timestamp": 125.0
307
}
308
```
309
310
### SourceRecord
311
312
A content source registered in the knowledge graph for provenance tracking.
313
314
| Field | Type | Default | Description |
315
|---|---|---|---|
316
| `source_id` | `str` | *required* | Unique identifier for this source |
317
| `source_type` | `str` | *required* | Source type: `"video"`, `"document"`, `"url"`, `"api"`, `"manual"` |
318
| `title` | `str` | *required* | Human-readable title |
319
| `path` | `Optional[str]` | `None` | Local file path |
320
| `url` | `Optional[str]` | `None` | URL if applicable |
321
| `mime_type` | `Optional[str]` | `None` | MIME type of the source |
322
| `ingested_at` | `str` | *auto* | ISO format ingestion timestamp (auto-generated) |
323
| `metadata` | `Dict[str, Any]` | `{}` | Additional source metadata |
324
325
```json
326
{
327
"source_id": "vid_abc123",
328
"source_type": "video",
329
"title": "Sprint Planning Meeting - Jan 15",
330
"path": "/recordings/sprint-planning.mp4",
331
"url": null,
332
"mime_type": "video/mp4",
333
"ingested_at": "2026-01-15T10:30:00",
334
"metadata": {"duration": 3600, "resolution": "1920x1080"}
335
}
336
```
337
338
### KnowledgeGraphData
339
340
Serializable knowledge graph data containing all nodes, relationships, and source provenance.
341
342
| Field | Type | Default | Description |
343
|---|---|---|---|
344
| `nodes` | `List[Entity]` | `[]` | Graph nodes/entities |
345
| `relationships` | `List[Relationship]` | `[]` | Graph relationships |
346
| `sources` | `List[SourceRecord]` | `[]` | Content sources for provenance tracking |
347
348
---
349
350
## Planning Models
351
352
### PlanningEntity
353
354
An entity classified for planning purposes, with priority and status tracking.
355
356
| Field | Type | Default | Description |
357
|---|---|---|---|
358
| `name` | `str` | *required* | Entity name |
359
| `planning_type` | `PlanningEntityType` | *required* | Planning classification |
360
| `description` | `str` | `""` | Detailed description |
361
| `priority` | `Optional[str]` | `None` | Priority: `"high"`, `"medium"`, `"low"` |
362
| `status` | `Optional[str]` | `None` | Status: `"identified"`, `"confirmed"`, `"resolved"` |
363
| `source_entities` | `List[str]` | `[]` | Names of source KG entities this was derived from |
364
| `metadata` | `Dict[str, Any]` | `{}` | Additional metadata |
365
366
```json
367
{
368
"name": "Migrate to OAuth 2.0",
369
"planning_type": "task",
370
"description": "Replace custom auth with OAuth 2.0 across all services",
371
"priority": "high",
372
"status": "identified",
373
"source_entities": ["OAuth", "Authentication Service"],
374
"metadata": {}
375
}
376
```
377
378
---
379
380
## Processing and Metadata Models
381
382
### ProcessingStats
383
384
Statistics about a processing run, including model usage tracking.
385
386
| Field | Type | Default | Description |
387
|---|---|---|---|
388
| `start_time` | `Optional[str]` | `None` | ISO format start time |
389
| `end_time` | `Optional[str]` | `None` | ISO format end time |
390
| `duration_seconds` | `Optional[float]` | `None` | Total processing time |
391
| `frames_extracted` | `int` | `0` | Number of frames extracted from video |
392
| `people_frames_filtered` | `int` | `0` | Frames filtered out (contained people/webcam) |
393
| `diagrams_detected` | `int` | `0` | Number of diagrams detected |
394
| `screen_captures` | `int` | `0` | Number of screen captures saved |
395
| `transcript_duration_seconds` | `Optional[float]` | `None` | Duration of transcribed audio |
396
| `models_used` | `Dict[str, str]` | `{}` | Map of task to model used (e.g., `{"vision": "gpt-4o"}`) |
397
398
### VideoMetadata
399
400
Metadata about the source video file.
401
402
| Field | Type | Default | Description |
403
|---|---|---|---|
404
| `title` | `str` | *required* | Video title |
405
| `source_path` | `Optional[str]` | `None` | Original video file path |
406
| `duration_seconds` | `Optional[float]` | `None` | Video duration in seconds |
407
| `resolution` | `Optional[str]` | `None` | Video resolution (e.g., `"1920x1080"`) |
408
| `processed_at` | `str` | *auto* | ISO format processing timestamp |
409
410
---
411
412
## Manifest Models
413
414
### VideoManifest
415
416
The single source of truth for a video processing run. Contains all output paths, inline structured data, and processing statistics.
417
418
| Field | Type | Default | Description |
419
|---|---|---|---|
420
| `version` | `str` | `"1.0"` | Manifest schema version |
421
| `video` | `VideoMetadata` | *required* | Source video metadata |
422
| `stats` | `ProcessingStats` | *default* | Processing statistics |
423
| `transcript_json` | `Optional[str]` | `None` | Relative path to transcript JSON |
424
| `transcript_txt` | `Optional[str]` | `None` | Relative path to transcript text |
425
| `transcript_srt` | `Optional[str]` | `None` | Relative path to SRT subtitles |
426
| `analysis_md` | `Optional[str]` | `None` | Relative path to analysis Markdown |
427
| `analysis_html` | `Optional[str]` | `None` | Relative path to analysis HTML |
428
| `analysis_pdf` | `Optional[str]` | `None` | Relative path to analysis PDF |
429
| `knowledge_graph_json` | `Optional[str]` | `None` | Relative path to knowledge graph JSON |
430
| `knowledge_graph_db` | `Optional[str]` | `None` | Relative path to knowledge graph DB |
431
| `key_points_json` | `Optional[str]` | `None` | Relative path to key points JSON |
432
| `action_items_json` | `Optional[str]` | `None` | Relative path to action items JSON |
433
| `key_points` | `List[KeyPoint]` | `[]` | Inline key points data |
434
| `action_items` | `List[ActionItem]` | `[]` | Inline action items data |
435
| `diagrams` | `List[DiagramResult]` | `[]` | Inline diagram results |
436
| `screen_captures` | `List[ScreenCapture]` | `[]` | Inline screen captures |
437
| `frame_paths` | `List[str]` | `[]` | Relative paths to extracted frames |
438
439
```python
440
from video_processor.models import VideoManifest, VideoMetadata
441
442
manifest = VideoManifest(
443
video=VideoMetadata(title="Sprint Planning"),
444
key_points=[...],
445
action_items=[...],
446
diagrams=[...],
447
)
448
449
# Serialize to JSON
450
manifest.model_dump_json(indent=2)
451
452
# Load from file
453
loaded = VideoManifest.model_validate_json(Path("manifest.json").read_text())
454
```
455
456
### BatchVideoEntry
457
458
Summary of a single video within a batch processing run.
459
460
| Field | Type | Default | Description |
461
|---|---|---|---|
462
| `video_name` | `str` | *required* | Video file name |
463
| `manifest_path` | `str` | *required* | Relative path to the video's manifest file |
464
| `status` | `str` | `"pending"` | Processing status: `"pending"`, `"completed"`, `"failed"` |
465
| `error` | `Optional[str]` | `None` | Error message if processing failed |
466
| `diagrams_count` | `int` | `0` | Number of diagrams detected |
467
| `action_items_count` | `int` | `0` | Number of action items extracted |
468
| `key_points_count` | `int` | `0` | Number of key points extracted |
469
| `duration_seconds` | `Optional[float]` | `None` | Processing duration |
470
471
### BatchManifest
472
473
Manifest for a batch processing run across multiple videos.
474
475
| Field | Type | Default | Description |
476
|---|---|---|---|
477
| `version` | `str` | `"1.0"` | Manifest schema version |
478
| `title` | `str` | `"Batch Processing Results"` | Batch title |
479
| `processed_at` | `str` | *auto* | ISO format timestamp |
480
| `stats` | `ProcessingStats` | *default* | Aggregated processing statistics |
481
| `videos` | `List[BatchVideoEntry]` | `[]` | Per-video summaries |
482
| `total_videos` | `int` | `0` | Total number of videos in batch |
483
| `completed_videos` | `int` | `0` | Successfully processed videos |
484
| `failed_videos` | `int` | `0` | Videos that failed processing |
485
| `total_diagrams` | `int` | `0` | Total diagrams across all videos |
486
| `total_action_items` | `int` | `0` | Total action items across all videos |
487
| `total_key_points` | `int` | `0` | Total key points across all videos |
488
| `batch_summary_md` | `Optional[str]` | `None` | Relative path to batch summary Markdown |
489
| `merged_knowledge_graph_json` | `Optional[str]` | `None` | Relative path to merged KG JSON |
490
| `merged_knowledge_graph_db` | `Optional[str]` | `None` | Relative path to merged KG database |
491
492
```python
493
from video_processor.models import BatchManifest
494
495
batch = BatchManifest(
496
title="Weekly Recordings",
497
total_videos=5,
498
completed_videos=4,
499
failed_videos=1,
500
)
501
```
502

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button