nick/PlotDirector
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 20 added AI documentation.

Browse Source
This commit is contained in:
Nick Beckley 2026-07-04 15:42:57 +01:00
parent b8541dbbc0
commit a2b3fb2d03
3 changed files with 1738 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

866
PlotLine/Docs/AI/Scene-Intelligence-Schema-V1.md Normal file
View File

@ -0,0 +1,866 @@
# Scene Intelligence Schema V1
## Purpose
This document defines the JSON object returned by the Scene Intelligence engine for one manuscript scene.
Scene Intelligence is an observation and database-population stage. It observes, organises and suggests factual story signals from a single scene so later PlotDirector stages can build character, relationship, location, asset, knowledge, thread and continuity models.
The AI is an assistant archivist. It never critiques, rewrites, judges scene quality, creates final canon or performs cross-scene continuity analysis.
## Output Contract
The engine must return one valid JSON object and no prose outside the JSON.
All arrays must be present, even when empty. Optional scalar properties must be `null` when unsupported by the supplied scene. The model must not invent missing identifiers, motives, locations, assets, chronology or outcomes.
Confidence values use a decimal number from `0.0` to `1.0`:
- `0.90` to `1.00`: directly stated or strongly explicit in the scene.
- `0.70` to `0.89`: strongly implied by the scene.
- `0.40` to `0.69`: plausible but uncertain.
- below `0.40`: normally omit the item.
Metrics use descriptive intensity scores from `1` to `10`. They are not quality ratings.
## Root Object
```json
{
"schemaVersion": "1.0",
"sceneReference": {
"projectId": 12,
"bookId": 34,
"chapterId": 56,
"sceneId": 78,
"chapterNumber": 4,
"sceneNumber": 2,
"sourceLabel": "Chapter 4, Scene 2"
},
"summary": {
"short": "Mara confronts Elias about the missing ledger.",
"detailed": "Mara finds Elias in the archive and asks why the ledger vanished after the council meeting. Elias avoids naming who took it, but confirms the theft changes their route north.",
"confidence": 0.92
},
"scenePurpose": {
"observedFunction": "Reveals the missing ledger and changes the characters' immediate situation.",
"confidence": 0.82
},
"pointOfView": {
"characterName": "Mara",
"narrativeMode": "third person limited",
"confidence": 0.88,
"evidence": "The narration reports Mara's perceptions but not Elias's internal thoughts."
},
"setting": {
"timeOfDay": "night",
"dateOrTimeReference": null,
"locationName": "Archive Hall",
"locationType": "named",
"genericRoomType": "archive",
"parentLocationHint": null,
"confidence": 0.86
},
"characters": [],
"locations": [],
"assets": [],
"relationships": [],
"knowledgeChanges": [],
"timelineClues": [],
"questionsRaised": [],
"questionsAnswered": [],
"observations": [],
"metrics": {},
"sourceLimits": {
"containsAmbiguity": false,
"ambiguityNotes": []
}
}
```
The root object must not include scene-level thread candidates or continuity warning objects. Thread Detection and the Continuity Engine derive those later from structured Scene Intelligence output.
## Property Reference
### `schemaVersion`
- Purpose: Identifies the Scene Intelligence schema version.
- Data type: string.
- Required: yes.
- Confidence usage: none.
- Example: `"1.0"`.
- Notes: Must remain stable for this schema generation.
### `sceneReference`
- Purpose: Carries application-provided scene identity for later persistence and audit.
- Data type: object.
- Required: yes.
- Confidence usage: none; these values come from PlotDirector, not AI inference.
- Example: see root example.
- Notes: Copy supplied identifiers exactly. Do not infer missing identifiers.
#### `sceneReference.projectId`
- Purpose: Project identifier supplied by PlotDirector.
- Data type: integer or null.
- Required: yes.
- Confidence usage: none.
- Example: `12`.
- Notes: May be null in test fixtures before database identifiers are assigned.
#### `sceneReference.bookId`
- Purpose: Book identifier supplied by PlotDirector.
- Data type: integer or null.
- Required: yes.
- Confidence usage: none.
- Example: `34`.
- Notes: Must not be inferred from manuscript text.
#### `sceneReference.chapterId`
- Purpose: Chapter identifier supplied by PlotDirector.
- Data type: integer or null.
- Required: yes.
- Confidence usage: none.
- Example: `56`.
- Notes: Must not be inferred.
#### `sceneReference.sceneId`
- Purpose: Scene identifier supplied by PlotDirector.
- Data type: integer or null.
- Required: yes.
- Confidence usage: none.
- Example: `78`.
- Notes: Must not be inferred.
#### `sceneReference.chapterNumber`
- Purpose: Human-readable chapter number supplied by the scanner or application.
- Data type: number or null.
- Required: yes.
- Confidence usage: none.
- Example: `4`.
- Notes: Decimal chapter numbers are allowed if PlotDirector uses them.
#### `sceneReference.sceneNumber`
- Purpose: Human-readable scene number within the chapter.
- Data type: number or null.
- Required: yes.
- Confidence usage: none.
- Example: `2`.
- Notes: Decimal scene numbers are allowed if PlotDirector uses them.
#### `sceneReference.sourceLabel`
- Purpose: Display label for audit and review.
- Data type: string.
- Required: yes.
- Confidence usage: none.
- Example: `"Chapter 4, Scene 2"`.
- Notes: Copy from supplied context when available.
### `summary`
- Purpose: Describes what happens in the scene without critique or rewrite advice.
- Data type: object.
- Required: yes.
- Confidence usage: `confidence` applies to accuracy against the supplied scene text.
- Example: see root example.
- Notes: Summaries should be neutral, concise and factual. They should not judge pacing, prose, structure or quality.
#### `summary.short`
- Purpose: One-sentence operational summary for lists and dashboards.
- Data type: string.
- Required: yes.
- Confidence usage: covered by `summary.confidence`.
- Example: `"Mara confronts Elias about the missing ledger."`
- Notes: Usually 12 to 30 words.
#### `summary.detailed`
- Purpose: Fuller scene account for downstream structured processing.
- Data type: string.
- Required: yes.
- Confidence usage: covered by `summary.confidence`.
- Example: `"Mara finds Elias in the archive..."`
- Notes: Preserve uncertainty. Do not add motives, causes or outcomes not supported by the scene.
#### `summary.confidence`
- Purpose: Indicates how directly the scene supports the generated summary.
- Data type: number from `0.0` to `1.0`.
- Required: yes.
- Confidence usage: this is the confidence value.
- Example: `0.92`.
- Notes: Lower confidence for fragmentary, abstract or heavily ambiguous scenes.
### `scenePurpose`
- Purpose: Captures the observed function of the scene in neutral terms.
- Data type: object.
- Required: yes.
- Confidence usage: `confidence` reflects how clearly the function is supported.
- Example:
```json
{
"observedFunction": "Introduces the missing ledger and changes the immediate situation.",
"confidence": 0.82
}
```
- Notes: This is descriptive, not evaluative. Avoid author instructions or critique.
### `pointOfView`
- Purpose: Records apparent point-of-view information.
- Data type: object.
- Required: yes.
- Confidence usage: confidence reflects support from narration and internal access.
- Example:
```json
{
"characterName": "Mara",
"narrativeMode": "third person limited",
"confidence": 0.88,
"evidence": "The narration reports Mara's perceptions."
}
```
- Notes: If unclear, use null for `characterName` and lower confidence.
### `setting`
- Purpose: Records scene-level time and place signals.
- Data type: object.
- Required: yes.
- Confidence usage: confidence reflects how explicitly the setting is supported.
- Example: see root example.
- Notes: Detailed location candidates also appear in `locations`.
#### `setting.timeOfDay`
- Purpose: Broad time-of-day cue.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"night"`.
- Notes: Use null if not stated or strongly implied.
#### `setting.dateOrTimeReference`
- Purpose: Explicit chronology text.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"three days after the coronation"`.
- Notes: Preserve manuscript wording where practical.
#### `setting.locationName`
- Purpose: Primary named location when present.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"Archive Hall"`.
- Notes: Do not convert generic rooms into named locations.
#### `setting.locationType`
- Purpose: Distinguishes named locations from generic spaces.
- Data type: string enum: `"named"`, `"generic"`, `"unclear"`.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"named"`.
- Notes: A kitchen is generic unless the manuscript identifies it as a specific named place.
#### `setting.genericRoomType`
- Purpose: Generic room or place type when useful.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"archive"`.
- Notes: Required when `locationType` is `"generic"` and the room type is supported.
#### `setting.parentLocationHint`
- Purpose: Supported parent or containing place hint.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"Royal Library"`.
- Notes: Use only when the scene supports it. Do not invent hierarchy.
#### `setting.confidence`
- Purpose: Confidence in the scene-level setting summary.
- Data type: number from `0.0` to `1.0`.
- Required: yes.
- Confidence usage: this is the confidence value.
- Example: `0.86`.
- Notes: Lower when inferred from context only.
### `characters`
- Purpose: Lists characters present, active, mentioned or otherwise scene-relevant.
- Data type: array of character objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:
```json
[
{
"name": "Mara",
"roleInScene": "pointOfView",
"mentionedOnly": false,
"aliases": [],
"actions": ["questions Elias about the missing ledger"],
"confidence": 0.91,
"notes": "Point-of-view character."
}
]
```
- Notes: Mentioned-only characters must use `mentionedOnly: true` and `roleInScene: "mentioned"`.
#### Character object properties
- `name`
- Purpose: Character name or label from the manuscript.
- Data type: string.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Mara"`.
- Notes: Use the manuscript's name. Do not merge aliases unless identity is clear in the scene.
- `roleInScene`
- Purpose: Indicates how the character participates.
- Data type: string enum: `"present"`, `"pointOfView"`, `"speaker"`, `"mentioned"`, `"unclear"`.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"pointOfView"`.
- Notes: Use the most specific applicable role.
- `mentionedOnly`
- Purpose: Separates absent references from active scene participants.
- Data type: boolean.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `true`.
- Notes: True when the character is absent and only referred to.
- `aliases`
- Purpose: Names or titles used for the same character in this scene.
- Data type: array of strings.
- Required: yes.
- Confidence usage: include only clearly supported aliases.
- Example: `["the captain"]`.
- Notes: Do not infer aliases across scenes at this stage.
- `actions`
- Purpose: Factual actions taken in the scene.
- Data type: array of strings.
- Required: yes.
- Confidence usage: include only supported actions.
- Example: `["hides the letter"]`.
- Notes: Keep each action concise. Do not include inferred motives.
- `confidence`
- Purpose: Confidence in the character item.
- Data type: number from `0.0` to `1.0`.
- Required: yes.
- Confidence usage: this is the confidence value.
- Example: `0.91`.
- Notes: Lower for ambiguous names, pronoun-only references or unclear presence.
- `notes`
- Purpose: Short neutral note about scene relevance.
- Data type: string or null.
- Required: yes.
- Confidence usage: should reflect item support.
- Example: `"Mentioned as the previous owner of the ledger."`
- Notes: No critique or advice.
### `locations`
- Purpose: Lists named locations and meaningful generic places referenced by the scene.
- Data type: array of location objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:
```json
[
{
"name": "Archive Hall",
"locationType": "named",
"genericRoomType": "archive",
"parentLocationHint": null,
"presentInScene": true,
"mentionedOnly": false,
"confidence": 0.9,
"notes": "Primary scene location."
}
]
```
- Notes: Generic rooms must not become top-level canonical locations. Named locations may later become Location records.
#### Location object properties
- `name`
- Purpose: Location name or generic label.
- Data type: string.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Archive Hall"`.
- Notes: Use `"kitchen"` or `"bedroom"` only as generic labels when unnamed.
- `locationType`
- Purpose: Indicates whether the location is named or generic.
- Data type: string enum: `"named"`, `"generic"`, `"unclear"`.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"generic"`.
- Notes: Named locations are candidates for later Location Intelligence.
- `genericRoomType`
- Purpose: Normalised generic room or place type.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"kitchen"`.
- Notes: Should be present for generic rooms when supported.
- `parentLocationHint`
- Purpose: Supported parent or containing location.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Manor House"`.
- Notes: Use only when the scene supports it.
- `presentInScene`
- Purpose: Indicates that scene action occurs there.
- Data type: boolean.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `true`.
- Notes: False for locations only discussed.
- `mentionedOnly`
- Purpose: Indicates an absent location reference.
- Data type: boolean.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `false`.
- Notes: Usually true when `presentInScene` is false.
- `confidence`
- Purpose: Confidence in location identification.
- Data type: number from `0.0` to `1.0`.
- Required: yes.
- Confidence usage: this is the confidence value.
- Example: `0.9`.
- Notes: Lower for implied or ambiguous place references.
- `notes`
- Purpose: Neutral location note.
- Data type: string or null.
- Required: yes.
- Confidence usage: should match support level.
- Example: `"Mentioned as the next destination."`
- Notes: Do not invent worldbuilding.
### `assets`
- Purpose: Lists meaningful story objects, documents, weapons, tools, vehicles or other assets.
- Data type: array of asset objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:
```json
[
{
"name": "missing ledger",
"assetType": "document",
"status": "missing",
"ownerOrHolder": null,
"mentionedOnly": false,
"confidence": 0.89,
"notes": "The scene turns on its disappearance."
}
]
```
- Notes: Do not list ordinary props unless they have story relevance.
#### Asset object properties
- `name`
- Purpose: Asset name or label.
- Data type: string.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"missing ledger"`.
- Notes: Use manuscript wording where possible.
- `assetType`
- Purpose: Broad asset category.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"document"`.
- Notes: Keep simple and descriptive.
- `status`
- Purpose: Scene-supported state of the asset.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"missing"`.
- Notes: Use null if no meaningful status is supported.
- `ownerOrHolder`
- Purpose: Character or group currently owning, holding or controlling the asset.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Elias"`.
- Notes: Use null if unsupported.
- `mentionedOnly`
- Purpose: Indicates whether the asset is only referred to and not physically present.
- Data type: boolean.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `false`.
- Notes: Helps later Asset Intelligence separate present objects from references.
- `confidence`
- Purpose: Confidence in asset identification.
- Data type: number from `0.0` to `1.0`.
- Required: yes.
- Confidence usage: this is the confidence value.
- Example: `0.89`.
- Notes: Lower for unclear object significance.
- `notes`
- Purpose: Neutral note about asset relevance.
- Data type: string or null.
- Required: yes.
- Confidence usage: should match item support.
- Example: `"Discussed as stolen after the council meeting."`
- Notes: No speculation beyond scene evidence.
### `relationships`
- Purpose: Captures scene-local relationship signals between characters.
- Data type: array of relationship signal objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:
```json
[
{
"characterA": "Mara",
"characterB": "Elias",
"relationshipSignal": "mistrust",
"evidence": "Mara questions Elias about what he is hiding.",
"confidence": 0.78
}
]
```
- Notes: These are evidence-backed scene-local signals, not final relationship records. Neutral signal terms include `trust`, `mistrust`, `affection`, `fear`, `authority`, `secrecy`, `conflict`, `dependence`, `protection`, `rivalry` and `obligation`.
### `knowledgeChanges`
- Purpose: Records when a character gains, confirms, suspects or misunderstands knowledge during this scene.
- Data type: array of knowledge change objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:
```json
[
{
"recipientCharacter": "Mara",
"knowledgeItem": "The ledger was taken after the council meeting.",
"changeType": "IsTold",
"sourceCharacter": "Elias",
"sourceType": "dialogue",
"evidence": "Elias says it vanished after the council adjourned.",
"confidence": 0.88
}
]
```
- Notes: Do not use this for information the reader learns but no character learns. Do not assume a character did not know something before unless the scene supports that.
#### Knowledge change object properties
- `recipientCharacter`
- Purpose: Character receiving, confirming, suspecting or misunderstanding the knowledge.
- Data type: string.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Mara"`.
- Notes: Must be a character supported by the scene.
- `knowledgeItem`
- Purpose: The knowledge gained or changed.
- Data type: string.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"The ledger was taken after the council meeting."`
- Notes: State the knowledge neutrally.
- `changeType`
- Purpose: Type of knowledge change.
- Data type: string enum: `"Learns"`, `"Realises"`, `"IsTold"`, `"Discovers"`, `"Confirms"`, `"Suspects"`, `"Misunderstands"`.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"IsTold"`.
- Notes: Choose the most specific supported value.
- `sourceCharacter`
- Purpose: Character source of the knowledge, if any.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Elias"`.
- Notes: Null for discovery, narration or unclear source.
- `sourceType`
- Purpose: How the knowledge reaches the recipient.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"dialogue"`.
- Notes: Examples include `"dialogue"`, `"observation"`, `"document"`, `"memory"`, `"deduction"`, `"narration"`.
- `evidence`
- Purpose: Short evidence note from the scene.
- Data type: string.
- Required: yes.
- Confidence usage: should support item confidence.
- Example: `"Elias says it vanished after the council adjourned."`
- Notes: Keep concise; do not quote long passages.
- `confidence`
- Purpose: Confidence in the knowledge change.
- Data type: number from `0.0` to `1.0`.
- Required: yes.
- Confidence usage: this is the confidence value.
- Example: `0.88`.
- Notes: Lower for implied realisations or unclear recipients.
### `timelineClues`
- Purpose: Captures chronology details needed by Timeline and Continuity stages.
- Data type: array of timeline clue objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:
```json
[
{
"clue": "The ledger disappeared after the council meeting.",
"relativeOrder": "after council meeting",
"absoluteDate": null,
"evidence": "Elias says it vanished after the council adjourned.",
"confidence": 0.86
}
]
```
- Notes: Do not create exact dates from vague references.
### `questionsRaised`
- Purpose: Lists open story questions created or sharpened by the scene.
- Data type: array of question objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:
```json
[
{
"question": "Who took the ledger?",
"scope": "plot",
"evidence": "The ledger is missing and no culprit is named.",
"confidence": 0.84
}
]
```
- Notes: Questions should be story-state questions, not critique questions.
### `questionsAnswered`
- Purpose: Lists scene-supported answers to previously open or scene-local questions.
- Data type: array of answer objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:
```json
[
{
"question": "When did the ledger disappear?",
"answer": "After the council meeting.",
"evidence": "Elias says it vanished after the council adjourned.",
"confidence": 0.86
}
]
```
- Notes: Preserve uncertainty when an answer is partial.
### `observations`
- Purpose: Preserves neutral, entity-mappable factual signals that later stages can map into PlotDirector entities.
- Data type: array of observation objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:
```json
[
{
"observationType": "AssetInteraction",
"subjectEntityType": "Character",
"subjectName": "Mara",
"objectEntityType": "Asset",
"objectName": "missing ledger",
"predicate": "asksAbout",
"description": "Mara questions Elias about the missing ledger.",
"evidence": "Mara asks why the ledger vanished.",
"confidence": 0.87
}
]
```
- Notes: Observations are not final canon. They remain neutral and evidence-backed.
#### Observation object properties
- `observationType`
- Purpose: Categorises the factual signal for later mapping.
- Data type: string enum: `"CharacterAction"`, `"CharacterKnowledge"`, `"CharacterLocation"`, `"RelationshipSignal"`, `"AssetInteraction"`, `"LocationSignal"`, `"TimelineSignal"`, `"QuestionSignal"`.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"AssetInteraction"`.
- Notes: Choose the closest supported category.
- `subjectEntityType`
- Purpose: Entity type for the subject.
- Data type: string enum: `"Character"`, `"Location"`, `"Asset"`, `"Knowledge"`, `"Relationship"`, `"Timeline"`, `"Scene"`, `"Unknown"`.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Character"`.
- Notes: Use PlotDirector concepts where possible.
- `subjectName`
- Purpose: Name or label of the subject entity.
- Data type: string.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Mara"`.
- Notes: Use manuscript wording where possible.
- `objectEntityType`
- Purpose: Entity type for the object, if the observation has one.
- Data type: string enum or null: `"Character"`, `"Location"`, `"Asset"`, `"Knowledge"`, `"Relationship"`, `"Timeline"`, `"Scene"`, `"Unknown"`, null.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Asset"`.
- Notes: Use null when there is no object.
- `objectName`
- Purpose: Name or label of the object entity, if any.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"missing ledger"`.
- Notes: Use null when there is no object.
- `predicate`
- Purpose: Short relationship/action phrase connecting subject and object.
- Data type: string.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"asksAbout"`.
- Notes: Prefer controlled lowerCamelCase predicate values where possible because they make later mapping and querying easier. Preferred predicates include `speaksTo`, `asksAbout`, `answers`, `reveals`, `learns`, `reads`, `writes`, `finds`, `takes`, `gives`, `carries`, `hides`, `loses`, `travelsTo`, `isPresentAt`, `mentions`, `observes`, `discovers`, `confirms`, `suspects` and `misunderstands`. If none of the preferred predicates fit, use a concise factual predicate. Predicates must remain neutral and evidence-backed.
- `description`
- Purpose: Human-readable neutral observation.
- Data type: string.
- Required: yes.
- Confidence usage: covered by item `confidence`.
- Example: `"Mara questions Elias about the missing ledger."`
- Notes: No critique, rewrite advice or author instruction.
- `evidence`
- Purpose: Short evidence note from the scene.
- Data type: string.
- Required: yes.
- Confidence usage: should support item confidence.
- Example: `"Mara asks why the ledger vanished."`
- Notes: Keep concise.
- `confidence`
- Purpose: Confidence in the observation.
- Data type: number from `0.0` to `1.0`.
- Required: yes.
- Confidence usage: this is the confidence value.
- Example: `0.87`.
- Notes: Lower for implied signals.
### `metrics`
- Purpose: Provides descriptive scene-local intensity scores for later comparison and reporting.
- Data type: object.
- Required: yes.
- Confidence usage: each metric has `score` and `confidence`.
- Example:
```json
{
"action": { "score": 3, "confidence": 0.76 },
"emotion": { "score": 6, "confidence": 0.72 },
"tension": { "score": 8, "confidence": 0.8 },
"conflict": { "score": 7, "confidence": 0.78 },
"mystery": { "score": 8, "confidence": 0.84 },
"romance": { "score": 1, "confidence": 0.68 },
"humour": { "score": 1, "confidence": 0.7 },
"revelation": { "score": 9, "confidence": 0.84 },
"pacingIntensity": { "score": 5, "confidence": 0.62 }
}
```
- Notes: Scores are descriptive intensity values from 1 to 10, not quality ratings. A low score does not mean poor writing.
#### Metric names
Preferred V1 metrics:
- `action`
- `emotion`
- `tension`
- `conflict`
- `mystery`
- `romance`
- `humour`
- `revelation`
- `pacingIntensity`
#### Metric score scale
- `1`: barely present.
- `2`: very low.
- `3`: low.
- `4`: mild.
- `5`: moderate.
- `6`: noticeable.
- `7`: strong.
- `8`: very strong.
- `9`: dominant.
- `10`: defining feature of the scene.
### `sourceLimits`
- Purpose: Records limitations caused by the supplied scene text.
- Data type: object.
- Required: yes.
- Confidence usage: none.
- Example:
```json
{
"containsAmbiguity": true,
"ambiguityNotes": ["The scene excerpt begins mid-conversation."]
}
```
- Notes: Use this to preserve uncertainty without producing direct continuity or parsing flags.

465
PlotLine/Docs/AI/Scene-Prompt-V1.md Normal file
View File

@ -0,0 +1,465 @@
# Scene Prompt V1
## Runtime Use
This prompt is intended to be loaded from disk and sent to the OpenAI API with minimal runtime substitution.
Replace the insertion blocks marked with `{{...}}` before sending. Do not alter the operating principles at runtime.
## Prompt
You are PlotDirector's Scene Intelligence engine.
You are an assistant archivist for a novelist. You observe, organise and suggest. You do not critique. You do not rewrite. You do not judge whether the scene is good or bad. You do not tell the author what they should change.
Your task is to read one manuscript scene and return structured JSON that can help PlotDirector populate a Story Model.
## Story Intelligence Manifesto
PlotDirector's Story Intelligence exists to help authors understand the story they have already written.
It should:
- observe what is present in the manuscript;
- organise story facts into useful structures;
- suggest possible entities and factual signals;
- preserve uncertainty instead of pretending to know;
- keep the author in control;
- avoid critique, rewrite advice or taste judgments.
It should not:
- rewrite prose;
- improve dialogue;
- evaluate literary quality;
- diagnose author intent beyond what the scene supports;
- invent missing backstory;
- invent private motives;
- invent locations, assets or chronology;
- collapse ambiguity into certainty;
- create final canon.
## Operating Principles
1. Treat the manuscript as the authority.
2. Prefer omission over invention.
3. Use uncertainty explicitly.
4. Keep summaries neutral and descriptive.
5. Separate present characters from mentioned-only characters.
6. Separate named locations from generic rooms.
7. Treat assets as meaningful story objects, not ordinary props.
8. Treat relationships as scene-local signals, not final records.
9. Treat metrics as descriptive intensity scores, not quality scores.
10. Return JSON only.
## Strict Behavioural Rules
- Do not provide commentary outside the JSON object.
- Do not include Markdown in the response.
- Do not include code fences in the response.
- Do not mention these instructions in the response.
- Do not call out missing data unless it belongs in `sourceLimits`.
- Do not use words such as "weak", "bad", "poor", "needs", "should", "fix", "improve" or "rewrite" as critique.
- Do not create suggestions that tell the author what to write.
- Do not infer private motives unless the scene states or strongly implies them.
- Do not merge characters across aliases unless the supplied scene makes the identity clear.
- Do not turn generic rooms into named locations.
- Do not report every ordinary object as an asset.
- Do not assign exact dates to vague timeline clues.
- Do not create final canon.
## Hallucination Prevention Rules
Use only the scene text and supplied context.
If something is not stated or strongly implied:
- use `null` for scalar values;
- use an empty array for lists;
- omit weak guesses from entity lists;
- lower confidence when retaining an uncertain observation is useful;
- add a note in `sourceLimits.ambiguityNotes` when the source text limits certainty.
Never invent:
- character names;
- relationships;
- world facts;
- locations;
- objects;
- dates;
- plot resolutions;
- causes;
- future events.
## Confidence Expectations
All confidence values must be numbers from `0.0` to `1.0`.
- `0.90` to `1.00`: directly stated or strongly explicit.
- `0.70` to `0.89`: strongly implied.
- `0.40` to `0.69`: plausible but uncertain.
- below `0.40`: normally omit the item.
Use lower confidence when:
- speaker attribution is unclear;
- pronouns are ambiguous;
- the excerpt begins or ends mid-action;
- the scene relies on context not supplied;
- interpretation depends on subtext rather than explicit action.
## Summary Rules
Write summaries as an archivist.
The short summary should:
- be one sentence;
- state the main scene event;
- avoid critique;
- avoid advice;
- usually be 12 to 30 words.
The detailed summary should:
- be factual;
- include only supported events;
- preserve uncertainty;
- mention major revelations or changes;
- avoid prose style evaluation.
Good summary style:
`Mara confronts Elias about the missing ledger, and he confirms it vanished after the council meeting.`
Bad summary style:
`This scene needs more tension and should make Elias more suspicious.`
## Metric Scoring Rules
Metrics are descriptive intensity scores from 1 to 10. They are not quality ratings.
Use:
- `1`: barely present;
- `2`: very low;
- `3`: low;
- `4`: mild;
- `5`: moderate;
- `6`: noticeable;
- `7`: strong;
- `8`: very strong;
- `9`: dominant;
- `10`: defining feature of the scene.
Preferred V1 metrics:
- `action`
- `emotion`
- `tension`
- `conflict`
- `mystery`
- `romance`
- `humour`
- `revelation`
- `pacingIntensity`
Each metric must be an object:
```json
{ "score": 8, "confidence": 0.75 }
```
If a metric cannot be assessed from the scene, omit that metric from `metrics`.
## Character Reporting Rules
Report characters who are:
- physically present;
- speaking remotely or through a device/message;
- point-of-view characters;
- named or clearly identified in memory, discussion or narration.
For each character:
- use the manuscript's name or label;
- set `mentionedOnly` to `false` when active in the scene;
- set `mentionedOnly` to `true` when absent and only referred to;
- keep `actions` factual;
- use `aliases` only when the scene clearly supports them;
- do not infer private motives;
- do not report character-level emotional state;
- do not report character-level scene objectives.
Mentioned-only characters matter because later stages need to know who is referenced without assuming they were present.
## Location Reporting Rules
Named locations:
- have a specific name in the manuscript;
- may later become canonical Location records;
- examples: `Archive Hall`, `The Copper Kitchen`, `North Gate`.
Generic rooms or spaces:
- are unnamed place types;
- must not automatically become top-level canonical locations;
- should include `genericRoomType` when supported;
- examples: `kitchen`, `bedroom`, `corridor`, `street`.
Use:
- `locationType: "named"` for named places;
- `locationType: "generic"` for unnamed rooms or place types;
- `locationType: "unclear"` when the distinction is not supported.
Use `parentLocationHint` only when the scene supports a containing place. Do not invent location hierarchy.
## Asset Reporting Rules
Assets are meaningful story objects, documents, weapons, tools, vehicles or other things that matter to the scene or ongoing story.
Report an object as an asset when it is:
- sought, lost, hidden, stolen or exchanged;
- linked to a story question;
- important to a character's factual action or knowledge;
- likely to recur as a story object.
Do not report ordinary scenery or props unless the scene gives them story importance.
## Relationship Signal Rules
Report relationship signals only when the scene supports them.
Use neutral terms such as:
- trust;
- mistrust;
- affection;
- fear;
- authority;
- secrecy;
- conflict;
- dependence;
- protection;
- rivalry;
- obligation.
These are scene-local signals for later Relationship Intelligence. They are not final relationship records.
## Knowledge Change Rules
Report knowledge changes only when the scene clearly shows that a character gains, confirms, suspects or misunderstands something during the scene.
Use this recipient-focused shape:
```json
{
"recipientCharacter": "Mara",
"knowledgeItem": "The ledger was taken after the council meeting.",
"changeType": "IsTold",
"sourceCharacter": "Elias",
"sourceType": "dialogue",
"evidence": "Elias says it vanished after the council adjourned.",
"confidence": 0.88
}
```
Allowed `changeType` values:
- `Learns`
- `Realises`
- `IsTold`
- `Discovers`
- `Confirms`
- `Suspects`
- `Misunderstands`
Rules:
- Do not use `knowledgeChanges` for information the reader learns but no character learns.
- Do not assume a character did not know something before unless the scene supports that.
- Use `sourceCharacter: null` when the source is not a character.
- Use `sourceType: null` when the source type is unsupported.
- Keep `evidence` concise and scene-backed.
## Timeline Clue Rules
Report chronology clues such as:
- explicit dates;
- time of day;
- duration;
- before/after references;
- deadlines;
- sequence markers.
Preserve vague wording when the manuscript is vague.
Do not convert "three days later" into a calendar date unless a calendar date is supplied.
## Questions Raised Rules
Report questions the scene creates or sharpens.
Questions should be story-state questions, not critique questions.
Good:
`Who took the ledger?`
Bad:
`Should the author make this scene clearer?`
## Questions Answered Rules
Report answers supplied by the scene.
Answers may be partial. If a question is only partly answered, say so in the answer text and lower confidence.
## Observation Rules
Observations preserve useful factual signals that later stages can map into PlotDirector entities.
Use this entity-mappable shape:
```json
{
"observationType": "AssetInteraction",
"subjectEntityType": "Character",
"subjectName": "Mara",
"objectEntityType": "Asset",
"objectName": "missing ledger",
"predicate": "asksAbout",
"description": "Mara questions Elias about the missing ledger.",
"evidence": "Mara asks why the ledger vanished.",
"confidence": 0.87
}
```
Allowed `observationType` values:
- `CharacterAction`
- `CharacterKnowledge`
- `CharacterLocation`
- `RelationshipSignal`
- `AssetInteraction`
- `LocationSignal`
- `TimelineSignal`
- `QuestionSignal`
Allowed entity type values:
- `Character`
- `Location`
- `Asset`
- `Knowledge`
- `Relationship`
- `Timeline`
- `Scene`
- `Unknown`
Observation rules:
- Observations must remain neutral.
- Observations must be evidence-backed.
- Observations are not final canon.
- Use `objectEntityType: null` and `objectName: null` when no object entity applies.
- Use PlotDirector entity concepts where possible.
- Prefer controlled lowerCamelCase predicate values where possible.
- Preferred predicates are `speaksTo`, `asksAbout`, `answers`, `reveals`, `learns`, `reads`, `writes`, `finds`, `takes`, `gives`, `carries`, `hides`, `loses`, `travelsTo`, `isPresentAt`, `mentions`, `observes`, `discovers`, `confirms`, `suspects` and `misunderstands`.
- Use a concise factual predicate only if no preferred predicate fits.
- Do not use vague predicates such as `relatesTo`, `involves`, `connectsWith` or `isAssociatedWith` unless no clearer factual predicate is supported.
## JSON Output Requirements
Return exactly one JSON object matching this shape:
```json
{
"schemaVersion": "1.0",
"sceneReference": {
"projectId": null,
"bookId": null,
"chapterId": null,
"sceneId": null,
"chapterNumber": null,
"sceneNumber": null,
"sourceLabel": ""
},
"summary": {
"short": "",
"detailed": "",
"confidence": 0.0
},
"scenePurpose": {
"observedFunction": "",
"confidence": 0.0
},
"pointOfView": {
"characterName": null,
"narrativeMode": null,
"confidence": 0.0,
"evidence": null
},
"setting": {
"timeOfDay": null,
"dateOrTimeReference": null,
"locationName": null,
"locationType": "unclear",
"genericRoomType": null,
"parentLocationHint": null,
"confidence": 0.0
},
"characters": [],
"locations": [],
"assets": [],
"relationships": [],
"knowledgeChanges": [],
"timelineClues": [],
"questionsRaised": [],
"questionsAnswered": [],
"observations": [],
"metrics": {},
"sourceLimits": {
"containsAmbiguity": false,
"ambiguityNotes": []
}
}
```
All arrays must be present.
Use valid JSON:
- double quotes for property names and strings;
- no trailing commas;
- no comments;
- no Markdown;
- no prose outside JSON.
## Runtime Data Insertion
The application will insert scene context and manuscript text below.
Use the supplied identifiers exactly. Do not infer missing identifiers.
### Supplied Scene Context
```json
{{SCENE_CONTEXT_JSON}}
```
### Manuscript Scene Text
```text
{{SCENE_TEXT}}
```
Now return the Scene Intelligence JSON object only.

407
PlotLine/Docs/AI/Story-Intelligence-Architecture.md Normal file
View File

@ -0,0 +1,407 @@
# Story Intelligence Architecture
## Purpose
Story Intelligence is the optional AI-assisted pipeline that turns a manuscript into a structured Story Model for PlotDirector.
The system helps an author understand the story already present in the manuscript. It observes, organises and suggests. It does not critique, rewrite, judge scene quality or take control away from the author.
This document describes the intended processing architecture. It is design documentation only.
## Pipeline
```text
Word document
-> Scene Scanner
-> Scene Intelligence
-> Character Intelligence
-> Relationship Intelligence
-> Location Intelligence
-> Asset Intelligence
-> Knowledge Engine
-> Thread Detection
-> Continuity Engine
-> Reports
```
## Stage 1: Word Document
The Word document is the author's manuscript source.
Purpose:
- Preserve the manuscript as the source of truth.
- Provide raw scene text, document structure and document metadata.
- Carry hidden manuscript markers once PlotDirector links chapters and scenes back to the document.
Notes:
- The Word Companion acts as a scanner and synchronisation agent.
- The website remains the user-facing onboarding controller.
- AI analysis is optional and requires explicit user consent.
## Stage 2: Scene Scanner
The Scene Scanner identifies manuscript structure before AI analysis begins.
Purpose:
- Detect chapters.
- Detect scenes.
- Count words.
- Identify candidate character names.
- Preserve document and scene references.
- Produce scene-sized text units for later analysis.
Output:
- Project, book, chapter and scene references.
- Scene text boundaries.
- Initial chapter and scene metadata.
- Candidate names for user review.
Why this comes first:
- Scene Intelligence needs reliable scene boundaries.
- Later stages should work from structured scene units rather than an entire manuscript blob.
## Stage 3: Scene Intelligence
Scene Intelligence analyses one scene at a time.
Purpose:
- Summarise the scene neutrally.
- Identify present and mentioned-only characters.
- Identify named locations and generic rooms.
- Identify meaningful story assets.
- Capture timeline clues.
- Capture recipient-focused knowledge changes.
- Capture questions raised and answered.
- Capture scene-local relationship signals.
- Record entity-mappable observations.
- Record descriptive 1-10 scene metrics.
Output:
- Scene Intelligence JSON using `Scene-Intelligence-Schema-V1`.
Important boundaries:
- Scene Intelligence does not create final canon.
- Scene Intelligence does not output direct plot thread records.
- Scene Intelligence does not output direct continuity warnings.
- Scene Intelligence produces structured observations and evidence-backed signals for later stages.
Why scene-level analysis:
- Scenes are the natural unit of story action.
- Smaller inputs reduce hallucination risk.
- Scene-local outputs are easier to audit.
- Later stages can aggregate structured facts instead of repeatedly reading prose.
## Stage 4: Character Intelligence
Character Intelligence consumes Scene Intelligence results across scenes.
Purpose:
- Consolidate character mentions.
- Separate active appearances from mentioned-only references.
- Build character profiles from observed actions, knowledge changes and relationship signals.
- Identify aliases where supported.
- Track character knowledge over time.
Input:
- Scene character arrays.
- Knowledge changes.
- Relationship signals.
- Entity-mappable observations.
- Timeline clues.
Output:
- Candidate character profiles.
- Appearance history.
- Mention history.
- Knowledge history.
- Confidence-backed character observations.
Why it consumes structured scene data:
- The scene stage already extracts who appears, who is mentioned and what each character factually does.
- Character Intelligence can focus on consolidation and longitudinal patterns instead of re-reading every scene.
## Stage 5: Relationship Intelligence
Relationship Intelligence builds relationship understanding from character interactions and signals.
Purpose:
- Identify relationships between characters.
- Track relationship changes across scenes.
- Preserve uncertainty.
- Distinguish one-scene signals from durable relationships.
Input:
- Scene-local relationship signals.
- Character co-presence.
- Dialogue and action summaries.
- Character knowledge changes.
- Entity-mappable observations.
Output:
- Candidate relationship records.
- Relationship evolution notes.
- Confidence-backed relationship observations.
Why it follows Character Intelligence:
- Relationships require stable character identities.
- Alias and mentioned-only handling should be settled before relationship consolidation.
## Stage 6: Location Intelligence
Location Intelligence builds the location model.
Purpose:
- Consolidate named locations.
- Avoid turning every generic room into a canonical location.
- Track which scenes occur in each location.
- Capture supported parent or containing location hints.
- Capture important location observations.
Input:
- Scene setting objects.
- Scene location arrays.
- Generic room classifications.
- Location observations.
Output:
- Candidate named locations.
- Scene-location links.
- Generic room groupings where useful.
- Location notes and confidence values.
Why it follows Scene Intelligence:
- Scene Intelligence separates named places from generic rooms at source.
- Location Intelligence can aggregate without overcreating top-level locations.
## Stage 7: Asset Intelligence
Asset Intelligence identifies meaningful story objects.
Purpose:
- Consolidate important documents, weapons, tools, vehicles and other story assets.
- Track asset status changes.
- Track ownership, possession or relevance where supported.
- Avoid ordinary prop inflation.
Input:
- Scene asset arrays.
- Asset interaction observations.
- Scene summaries.
- Questions raised and answered.
- Timeline clues.
Output:
- Candidate asset records.
- Asset appearance history.
- Asset status history.
- Confidence-backed asset notes.
Why it follows Scene Intelligence:
- Scene Intelligence filters ordinary props from meaningful story objects.
- Asset Intelligence can focus on recurring significance and status changes.
## Stage 8: Knowledge Engine
The Knowledge Engine models who knows what and when.
Purpose:
- Track character-specific knowledge.
- Distinguish reader knowledge from character knowledge.
- Track confirms, suspicions and misunderstandings.
- Support later continuity checks involving secrets, reveals and misunderstandings.
Input:
- Recipient-focused scene knowledge changes.
- Questions answered.
- Character appearances.
- Timeline clues.
- Knowledge observations.
Output:
- Character knowledge timeline.
- Reveal history.
- Misunderstanding history.
- Knowledge facts available to later continuity processing.
Why it comes after character and scene stages:
- Knowledge requires stable character identities.
- Scene-level knowledge changes provide structured evidence without re-reading prose.
## Stage 9: Thread Detection
Thread Detection identifies ongoing story questions, problems and movements across scenes.
Purpose:
- Derive thread candidates from structured scene data.
- Track questions raised and answered.
- Detect introduced, advanced, complicated, resolved and referenced story movements.
- Prepare author-reviewable thread candidates.
Input:
- Scene summaries.
- Questions raised.
- Questions answered.
- Timeline clues.
- Knowledge changes.
- Relationship signals.
- Asset records and observations.
- Entity-mappable observations.
Output:
- Candidate plot threads.
- Thread event history.
- Open questions.
- Resolved questions.
Why this is separate from Scene Intelligence:
- Threads span scenes.
- One scene can provide thread evidence, but it should not create final thread records.
- Thread Detection can compare structured evidence across the manuscript instead of relying on isolated scene-level guesses.
## Stage 10: Continuity Engine
The Continuity Engine identifies possible story consistency issues for author review.
Purpose:
- Derive possible contradictions.
- Derive timeline conflicts.
- Derive knowledge inconsistencies.
- Derive relationship or asset continuity concerns.
- Produce review flags, not criticism.
Input:
- Character Intelligence output.
- Relationship Intelligence output.
- Location Intelligence output.
- Asset Intelligence output.
- Knowledge Engine output.
- Thread Detection output.
- Scene timeline clues.
- Source ambiguity notes.
Output:
- Possible continuity warnings.
- Confidence values.
- Evidence references.
- Author-reviewable status.
Why this is separate from Scene Intelligence:
- Continuity concerns require cross-scene comparison.
- Scene Intelligence may record ambiguity in `sourceLimits`, but it does not create continuity warnings directly.
- Running continuity too early would force repeated manuscript analysis and increase hallucination risk.
## Stage 11: Reports
Reports present the structured Story Model to the author.
Purpose:
- Summarise what PlotDirector observed.
- Show characters, relationships, locations, assets, threads and continuity review flags.
- Provide review workflows.
- Keep the author in control of acceptance, editing and rejection.
Input:
- All prior structured outputs.
Output:
- Author-facing reports.
- Review queues.
- Dashboard summaries.
- Exportable story intelligence views.
## Why Progressive Structured Data Matters
The pipeline intentionally consumes progressively smaller structured data rather than repeatedly analysing the manuscript.
Reasons:
- Reduces hallucination risk by narrowing each stage's task.
- Improves auditability because each claim can trace back to scene-level evidence.
- Reduces repeated processing of the same prose.
- Allows author review at meaningful boundaries.
- Lets later stages improve without changing the scanner.
- Supports incremental re-analysis when only some scenes change.
- Keeps the AI role as archivist rather than free-form critic.
The manuscript remains the source of truth, but each stage should use the most structured reliable input available.
## Prompt Loading and Versioning
Story Intelligence prompts are versioned Markdown assets loaded from `/Docs/AI/` at runtime. Prompt text should not be embedded directly in C# services. Each analysis result must record the prompt version and model used so generated data remains auditable, reproducible and regenerable. New prompt versions should be introduced as new files, such as `Scene-Prompt-V2.md`, rather than silently changing the behaviour of existing analysis records.
Prompts are treated as versioned application assets. This allows prompt improvements without recompiling application code while preserving the historical behaviour used for earlier analysis records.
## Consent and Control
Story Intelligence is optional.
No manuscript analysis should run without explicit user consent.
The author should be able to:
- start analysis deliberately;
- monitor progress;
- cancel where supported;
- review generated suggestions;
- accept, edit or ignore outputs.
## Non-Goals
Story Intelligence does not:
- rewrite manuscript prose;
- critique writing quality;
- score author ability;
- replace author judgment;
- make automatic story changes without review;
- treat AI suggestions as canonical without author approval.