@sudobility/screenwriter_types 0.1.1

package/dist/ai/index.d.ts

@@ -0,0 +1,564 @@
+import { z } from 'zod';
+/**
+ * AI features (spec 06): script review and polish through ShapeShyft.
+ *
+ * Only the tasks implemented so far are in `AI_TASKS`; adding one means a registry row in
+ * `screenwriter_api/src/services/ai/tasks.ts`, a prompt builder, an output schema here and a fixture.
+ * Output schemas are written for structured output: every field is required (nullable, never optional)
+ * and objects are closed, so `z.toJSONSchema` gives the exact schema to store on the ShapeShyft endpoint.
+ */
+export declare const AI_TASKS: readonly ["coverage", "polish.dialogue"];
+export type AiTask = (typeof AI_TASKS)[number];
+export declare const aiTaskSchema: z.ZodEnum<{
+    coverage: "coverage";
+    "polish.dialogue": "polish.dialogue";
+}>;
+/** ShapeShyft endpoint names (spec 06 2.1). `summarize-chunk` is stage 1 of a long coverage run. */
+export declare const AI_ENDPOINTS: readonly ["coverage-review", "polish", "summarize-chunk"];
+export type AiEndpoint = (typeof AI_ENDPOINTS)[number];
+export declare const AI_JOB_STATUSES: readonly ["queued", "running", "succeeded", "failed", "cancelled"];
+export type AiJobStatus = (typeof AI_JOB_STATUSES)[number];
+/** Counted limits, declared once: schemas, validators and prompt text all read these. */
+export declare const AI_LIMITS: {
+    readonly noteTitleMax: 80;
+    readonly noteBodyMax: 1200;
+    readonly noteAnchorsMax: 8;
+    readonly strengthsMax: 8;
+    readonly weaknessesMax: 12;
+    readonly sceneNotesMax: 20;
+    readonly loglineMax: 300;
+    readonly summaryMax: 4000;
+    readonly genreMax: 3;
+    readonly verdictRationaleMax: 800;
+    readonly polishSuggestionsMax: 200;
+    readonly polishTextMax: 4000;
+    readonly rationaleMax: 400;
+    readonly chunkSummaryMax: 1200;
+    readonly sceneSummaryMax: 280;
+    readonly polishMaxScenes: 8;
+    readonly instructionsMax: 500;
+};
+export declare const REVIEW_CATEGORIES: readonly ["premise", "structure", "character", "dialogue", "pacing", "tone", "theme", "worldbuilding", "format", "marketability", "clarity", "continuity"];
+export type ReviewCategory = (typeof REVIEW_CATEGORIES)[number];
+export declare const SEVERITIES: readonly ["praise", "minor", "moderate", "major"];
+export type Severity = (typeof SEVERITIES)[number];
+export declare const COVERAGE_VERDICTS: readonly ["recommend", "consider", "pass"];
+/** Where a note points. `elementId: null` means the whole scene. The server adds the content hash. */
+export declare const anchorRefSchema: z.ZodObject<{
+    sceneId: z.ZodString;
+    elementId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AnchorRef = z.infer<typeof anchorRefSchema>;
+export declare const noteSchema: z.ZodObject<{
+    category: z.ZodEnum<{
+        format: "format";
+        premise: "premise";
+        structure: "structure";
+        character: "character";
+        dialogue: "dialogue";
+        pacing: "pacing";
+        tone: "tone";
+        theme: "theme";
+        worldbuilding: "worldbuilding";
+        marketability: "marketability";
+        clarity: "clarity";
+        continuity: "continuity";
+    }>;
+    severity: z.ZodEnum<{
+        praise: "praise";
+        minor: "minor";
+        moderate: "moderate";
+        major: "major";
+    }>;
+    title: z.ZodString;
+    body: z.ZodString;
+    anchors: z.ZodArray<z.ZodObject<{
+        sceneId: z.ZodString;
+        elementId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ModelNote = z.infer<typeof noteSchema>;
+/** `coverage-review` output. */
+export declare const coverageResponseSchema: z.ZodObject<{
+    logline: z.ZodString;
+    summary: z.ZodString;
+    genre: z.ZodArray<z.ZodString>;
+    strengths: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            format: "format";
+            premise: "premise";
+            structure: "structure";
+            character: "character";
+            dialogue: "dialogue";
+            pacing: "pacing";
+            tone: "tone";
+            theme: "theme";
+            worldbuilding: "worldbuilding";
+            marketability: "marketability";
+            clarity: "clarity";
+            continuity: "continuity";
+        }>;
+        severity: z.ZodEnum<{
+            praise: "praise";
+            minor: "minor";
+            moderate: "moderate";
+            major: "major";
+        }>;
+        title: z.ZodString;
+        body: z.ZodString;
+        anchors: z.ZodArray<z.ZodObject<{
+            sceneId: z.ZodString;
+            elementId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    weaknesses: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            format: "format";
+            premise: "premise";
+            structure: "structure";
+            character: "character";
+            dialogue: "dialogue";
+            pacing: "pacing";
+            tone: "tone";
+            theme: "theme";
+            worldbuilding: "worldbuilding";
+            marketability: "marketability";
+            clarity: "clarity";
+            continuity: "continuity";
+        }>;
+        severity: z.ZodEnum<{
+            praise: "praise";
+            minor: "minor";
+            moderate: "moderate";
+            major: "major";
+        }>;
+        title: z.ZodString;
+        body: z.ZodString;
+        anchors: z.ZodArray<z.ZodObject<{
+            sceneId: z.ZodString;
+            elementId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    sceneNotes: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            format: "format";
+            premise: "premise";
+            structure: "structure";
+            character: "character";
+            dialogue: "dialogue";
+            pacing: "pacing";
+            tone: "tone";
+            theme: "theme";
+            worldbuilding: "worldbuilding";
+            marketability: "marketability";
+            clarity: "clarity";
+            continuity: "continuity";
+        }>;
+        severity: z.ZodEnum<{
+            praise: "praise";
+            minor: "minor";
+            moderate: "moderate";
+            major: "major";
+        }>;
+        title: z.ZodString;
+        body: z.ZodString;
+        anchors: z.ZodArray<z.ZodObject<{
+            sceneId: z.ZodString;
+            elementId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    verdict: z.ZodEnum<{
+        recommend: "recommend";
+        consider: "consider";
+        pass: "pass";
+    }>;
+    verdictRationale: z.ZodString;
+}, z.core.$strip>;
+export type CoverageResponse = z.infer<typeof coverageResponseSchema>;
+/** `polish` output: one proposed replacement per element. */
+export declare const polishResponseSchema: z.ZodObject<{
+    suggestions: z.ZodArray<z.ZodObject<{
+        elementId: z.ZodString;
+        after: z.ZodString;
+        rationale: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PolishResponse = z.infer<typeof polishResponseSchema>;
+/** `summarize-chunk` output (stage 1 of a long-script coverage run). */
+export declare const chunkSummaryResponseSchema: z.ZodObject<{
+    scenes: z.ZodArray<z.ZodObject<{
+        sceneId: z.ZodString;
+        summary: z.ZodString;
+        intensity: z.ZodNumber;
+    }, z.core.$strip>>;
+    chunkSummary: z.ZodString;
+}, z.core.$strip>;
+export type ChunkSummaryResponse = z.infer<typeof chunkSummaryResponseSchema>;
+/** The five input fields every endpoint takes (spec 06 2.1). */
+export declare const aiEndpointInputSchema: z.ZodObject<{
+    context: z.ZodString;
+    brief: z.ZodString;
+    max_output_tokens: z.ZodNumber;
+    locale: z.ZodString;
+    script_language: z.ZodString;
+}, z.core.$strip>;
+export type AiEndpointInput = z.infer<typeof aiEndpointInputSchema>;
+/** Endpoint -> output schema. `bun run ai:schemas` in screenwriter_api prints these as JSON Schema. */
+export declare const AI_ENDPOINT_OUTPUT_SCHEMAS: {
+    readonly 'coverage-review': z.ZodObject<{
+        logline: z.ZodString;
+        summary: z.ZodString;
+        genre: z.ZodArray<z.ZodString>;
+        strengths: z.ZodArray<z.ZodObject<{
+            category: z.ZodEnum<{
+                format: "format";
+                premise: "premise";
+                structure: "structure";
+                character: "character";
+                dialogue: "dialogue";
+                pacing: "pacing";
+                tone: "tone";
+                theme: "theme";
+                worldbuilding: "worldbuilding";
+                marketability: "marketability";
+                clarity: "clarity";
+                continuity: "continuity";
+            }>;
+            severity: z.ZodEnum<{
+                praise: "praise";
+                minor: "minor";
+                moderate: "moderate";
+                major: "major";
+            }>;
+            title: z.ZodString;
+            body: z.ZodString;
+            anchors: z.ZodArray<z.ZodObject<{
+                sceneId: z.ZodString;
+                elementId: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        weaknesses: z.ZodArray<z.ZodObject<{
+            category: z.ZodEnum<{
+                format: "format";
+                premise: "premise";
+                structure: "structure";
+                character: "character";
+                dialogue: "dialogue";
+                pacing: "pacing";
+                tone: "tone";
+                theme: "theme";
+                worldbuilding: "worldbuilding";
+                marketability: "marketability";
+                clarity: "clarity";
+                continuity: "continuity";
+            }>;
+            severity: z.ZodEnum<{
+                praise: "praise";
+                minor: "minor";
+                moderate: "moderate";
+                major: "major";
+            }>;
+            title: z.ZodString;
+            body: z.ZodString;
+            anchors: z.ZodArray<z.ZodObject<{
+                sceneId: z.ZodString;
+                elementId: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        sceneNotes: z.ZodArray<z.ZodObject<{
+            category: z.ZodEnum<{
+                format: "format";
+                premise: "premise";
+                structure: "structure";
+                character: "character";
+                dialogue: "dialogue";
+                pacing: "pacing";
+                tone: "tone";
+                theme: "theme";
+                worldbuilding: "worldbuilding";
+                marketability: "marketability";
+                clarity: "clarity";
+                continuity: "continuity";
+            }>;
+            severity: z.ZodEnum<{
+                praise: "praise";
+                minor: "minor";
+                moderate: "moderate";
+                major: "major";
+            }>;
+            title: z.ZodString;
+            body: z.ZodString;
+            anchors: z.ZodArray<z.ZodObject<{
+                sceneId: z.ZodString;
+                elementId: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        verdict: z.ZodEnum<{
+            recommend: "recommend";
+            consider: "consider";
+            pass: "pass";
+        }>;
+        verdictRationale: z.ZodString;
+    }, z.core.$strip>;
+    readonly polish: z.ZodObject<{
+        suggestions: z.ZodArray<z.ZodObject<{
+            elementId: z.ZodString;
+            after: z.ZodString;
+            rationale: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    readonly 'summarize-chunk': z.ZodObject<{
+        scenes: z.ZodArray<z.ZodObject<{
+            sceneId: z.ZodString;
+            summary: z.ZodString;
+            intensity: z.ZodNumber;
+        }, z.core.$strip>>;
+        chunkSummary: z.ZodString;
+    }, z.core.$strip>;
+};
+export interface Anchor {
+    sceneId: string;
+    elementId?: string;
+    /** Content hash (spec 11 4.2) of the element, or of the scene when there is no elementId, at generation time. */
+    contentHash: string;
+}
+export interface AiNote {
+    id: string;
+    category: ReviewCategory;
+    severity: Severity;
+    title: string;
+    body: string;
+    anchors: Anchor[];
+}
+export interface CoverageReport {
+    logline: string;
+    summary: string;
+    genre: string[];
+    verdict: (typeof COVERAGE_VERDICTS)[number];
+    verdictRationale: string;
+    strengths: AiNote[];
+    weaknesses: AiNote[];
+    notesByScene: {
+        sceneId: string;
+        heading: string;
+        notes: AiNote[];
+    }[];
+    stats: {
+        scenes: number;
+        chunks: number;
+        droppedItems: number;
+    };
+}
+export interface AiTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    calls: number;
+    model: string | null;
+}
+export declare const aiScopeSchema: z.ZodObject<{
+    sceneIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    elementIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AiScope = z.infer<typeof aiScopeSchema>;
+export declare const aiJobOptionsSchema: z.ZodObject<{
+    instructions: z.ZodOptional<z.ZodString>;
+    intensity: z.ZodOptional<z.ZodEnum<{
+        bold: "bold";
+        light: "light";
+        medium: "medium";
+    }>>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AiJobOptions = z.infer<typeof aiJobOptionsSchema>;
+/** `POST /documents/:did/ai/jobs` body. `polish.dialogue` needs a scope; `coverage` defaults to the whole script. */
+export declare const aiJobCreateSchema: z.ZodObject<{
+    task: z.ZodEnum<{
+        coverage: "coverage";
+        "polish.dialogue": "polish.dialogue";
+    }>;
+    scope: z.ZodOptional<z.ZodObject<{
+        sceneIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        elementIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    options: z.ZodOptional<z.ZodObject<{
+        instructions: z.ZodOptional<z.ZodString>;
+        intensity: z.ZodOptional<z.ZodEnum<{
+            bold: "bold";
+            light: "light";
+            medium: "medium";
+        }>>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AiJobCreateRequest = z.infer<typeof aiJobCreateSchema>;
+/** 202 response. */
+export interface AiJobCreated {
+    jobId: string;
+    status: 'queued';
+}
+export interface AiJobProgress {
+    stage: string;
+    done: number;
+    total: number;
+}
+export interface AiJobError {
+    code: string;
+    message: string;
+}
+export type AiJobResult = {
+    kind: 'report';
+    report: CoverageReport;
+}
+/** `suggestionSetId` is null when the model found nothing worth changing (count 0). */
+ | {
+    kind: 'suggestions';
+    suggestionSetId: string | null;
+    count: number;
+    droppedItems: number;
+};
+/** `GET /ai/jobs/:jobId` and the items of `GET /documents/:did/ai/jobs`. Poll until `status` is final. */
+export interface AiJob {
+    id: string;
+    documentId: string;
+    task: AiTask;
+    status: AiJobStatus;
+    progress?: AiJobProgress;
+    result?: AiJobResult;
+    error?: AiJobError;
+    promptVersion: string;
+    usage?: AiTokenUsage;
+    createdAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+export declare const SUGGESTION_STATUSES: readonly ["pending", "accepted", "rejected", "stale"];
+export type SuggestionStatus = (typeof SUGGESTION_STATUSES)[number];
+export declare const SUGGESTION_SET_STATUSES: readonly ["pending", "partiallyAccepted", "accepted", "rejected", "stale", "expired"];
+export type SuggestionSetStatus = (typeof SUGGESTION_SET_STATUSES)[number];
+export interface Suggestion {
+    id: string;
+    elementId: string;
+    kind: 'replaceText';
+    before: string;
+    after: string;
+    rationale: string;
+    /** The element's content hash when the suggestion was generated; accepting checks it. */
+    contentHash: string;
+    status: SuggestionStatus;
+    decidedAt: string | null;
+}
+export interface SuggestionSetSummary {
+    id: string;
+    documentId: string;
+    jobId: string;
+    task: AiTask;
+    promptVersion: string;
+    status: SuggestionSetStatus;
+    sourceEpoch: number;
+    counts: Record<SuggestionStatus, number>;
+    createdAt: string;
+}
+export interface SuggestionSet extends SuggestionSetSummary {
+    suggestions: Suggestion[];
+}
+export declare const suggestionAcceptSchema: z.ZodObject<{
+    suggestionIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type SuggestionAcceptRequest = z.infer<typeof suggestionAcceptSchema>;
+/** `reject` with no ids rejects every pending suggestion in the set. */
+export declare const suggestionRejectSchema: z.ZodObject<{
+    suggestionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type SuggestionRejectRequest = z.infer<typeof suggestionRejectSchema>;
+export interface SuggestionAcceptResponse {
+    applied: string[];
+    set: SuggestionSet;
+}
+/** `fixture` = canned test-mode answers (AI_TEST_MODE=1); `live` = ShapeShyft configured; `unavailable` = neither. */
+export type AiStatusMode = 'live' | 'fixture' | 'unavailable';
+/** `GET /ai/status`. */
+export interface AiStatus {
+    available: boolean;
+    mode: AiStatusMode;
+}
+/** Bumping this requires every user to re-accept before their next AI job. */
+export declare const AI_CONSENT_VERSION = 1;
+/** `GET /me/ai-consents`. */
+export interface AiConsentStatus {
+    currentVersion: number;
+    acceptedVersion: number | null;
+    acceptedAt: string | null;
+}
+/** `POST /me/ai-consents`: `version` must equal `AI_CONSENT_VERSION`, else `VALIDATION`. */
+export declare const aiConsentAcceptSchema: z.ZodObject<{
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type AiConsentAcceptRequest = z.infer<typeof aiConsentAcceptSchema>;
+export interface AiConsentAcceptResponse {
+    acceptedVersion: number;
+    acceptedAt: string;
+}
+/** What a quote was computed from. Pages are approximated from word count until the paginator runs server-side (M2). */
+export interface AiPriceBasis {
+    pages: number;
+    scopePages?: number;
+}
+export declare const aiEstimateRequestSchema: z.ZodObject<{
+    task: z.ZodEnum<{
+        coverage: "coverage";
+        "polish.dialogue": "polish.dialogue";
+    }>;
+    scope: z.ZodOptional<z.ZodObject<{
+        sceneIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        elementIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type AiEstimateRequest = z.infer<typeof aiEstimateRequestSchema>;
+/** `POST /documents/:did/ai/estimate`: the same pricing function `startJob` charges at, run without creating a job. */
+export interface AiEstimateResponse {
+    credits: number;
+    basis: AiPriceBasis;
+    withinLimit: boolean;
+    balance: number;
+}
+/** `GET /me/ai-activity`, `GET /workspaces/:wid/ai-activity` (the latter adds `userId`). */
+export interface AiActivityItem {
+    jobId: string;
+    task: AiTask;
+    documentId: string;
+    documentTitle: string;
+    status: AiJobStatus;
+    quotedCredits: number | null;
+    chargedCredits: number | null;
+    refundedCredits: number | null;
+    createdAt: string;
+}
+/** `GET /documents/:did/ai/reports`: a saved coverage/review job, summarised. */
+export interface AiReportSummary {
+    jobId: string;
+    task: AiTask;
+    status: AiJobStatus;
+    createdAt: string;
+    finishedAt: string | null;
+}
+/** `POST .../reports/:jobId/notes/:noteId/convert`: `noteId` is `"strengths:<i>" | "weaknesses:<i>" | "sceneNotes:<i>"`,
+ *  the note's position in the immutable stored report (reports have no independently stable note ids). */
+export interface AiNoteConvertResponse {
+    scriptNoteId: string;
+}
+export declare const suggestionDecideSchema: z.ZodObject<{
+    accept: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"allPending">]>;
+    reject: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"allPending">]>;
+    expectedHashes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SuggestionDecideRequest = z.infer<typeof suggestionDecideSchema>;
+export interface SuggestionDecideResponse {
+    accepted: string[];
+    rejected: string[];
+    skippedStale: string[];
+    skippedConflicted: string[];
+    autoSnapshotId: string | null;
+    epoch: number;
+}