@sudobility/screenwriter_types 0.1.2 → 0.1.4

package/dist/api/routes.d.ts

@@ -69,6 +69,10 @@ export declare const API_ROUTES: {
     readonly apiKeyUpdate: RouteSpec;
     readonly apiKeyRevoke: RouteSpec;
     readonly aiStatus: RouteSpec;
+    readonly aiGenerateCharacterSkeleton: RouteSpec;
+    readonly aiGenerateScript: RouteSpec;
+    readonly aiPolishCharacterDialogue: RouteSpec;
+    readonly aiPolishScene: RouteSpec;
     readonly aiJobCreate: RouteSpec;
     readonly aiJobsList: RouteSpec;
     readonly aiJobGet: RouteSpec;

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export * from './formats/index.js';
 export * from './io/index.js';
 export * from './keys/index.js';
 export * from './ai/index.js';
+export * from './ai/actions.js';
 export * from './jobs/index.js';
 export * from './reads/index.js';
 export * from './reports/index.js';

package/dist/index.js

@@ -337,6 +337,15 @@ const API_ROUTES = {
   // B7 AI: script review and polish. Keys need the `ai` flag (403 AI_KEY_NOT_PERMITTED) and, to start
   // jobs or decide suggestions, read_write scope.
   aiStatus: r("GET", "/ai/status", "U,Kr"),
+  // Synchronous AI actions (`ai/actions.ts`): user principals only, gated by AI consent, a daily limit and credits.
+  aiGenerateCharacterSkeleton: r(
+    "POST",
+    "/ai/generate-character-skeleton",
+    "U"
+  ),
+  aiGenerateScript: r("POST", "/ai/generate-script", "U"),
+  aiPolishCharacterDialogue: r("POST", "/ai/polish-character-dialogue", "U"),
+  aiPolishScene: r("POST", "/ai/polish-scene", "U"),
   aiJobCreate: r("POST", "/documents/:did/ai/jobs", "U,Krw", "ai.run"),
   aiJobsList: r("GET", "/documents/:did/ai/jobs", "U,Kr", "document.read"),
   aiJobGet: r("GET", "/ai/jobs/:jobId", "U,Kr", "document.read"),
@@ -1451,7 +1460,8 @@ const documentViewStatePutSchema = documentViewStateSchema.extend({
 const templateListQuerySchema = z.object({
   category: z.string().optional(),
   workspaceId: z.string().optional(),
-  scope: z.enum(["builtin", "user", "workspace"]).optional()
+  scope: z.enum(["builtin", "user", "workspace"]).optional(),
+  locale: z.string().optional()
 });
 const templateGetQuerySchema = z.object({
   version: z.coerce.number().int().min(1).optional()
@@ -1988,6 +1998,200 @@ const suggestionDecideSchema = z.object({
   expectedHashes: z.record(z.string(), z.string()).optional(),
   dryRun: z.boolean().optional()
 });
+const AI_ACTIONS = [
+  "generate-character-skeleton",
+  "generate-script",
+  "polish-character-dialogue",
+  "polish-scene"
+];
+const aiActionSchema = z.enum(AI_ACTIONS);
+const AI_ACTION_LIMITS = {
+  /** Free-form text a writer pastes in: a character description, or the story to turn into a script. */
+  descriptionMax: 8e3,
+  storyMax: 3e4,
+  skeletonFieldMax: 1e3,
+  characterNameMax: 80,
+  languageMax: 35,
+  /** Dialogue polish: one character's lines. */
+  dialoguesMax: 100,
+  dialogueTextMax: 2e3,
+  /** Scene polish. */
+  sceneElementsMax: 300,
+  sceneElementTextMax: 2e3,
+  sceneCharactersMax: 20,
+  /** Script generation output. */
+  scenesMax: 40,
+  elementsPerSceneMax: 200,
+  elementTextMax: 2e3,
+  titleMax: 120,
+  locationMax: 120,
+  timeMax: 40,
+  idMax: 64
+};
+const CHARACTER_SKELETON_FIELDS = {
+  physical: [
+    "age",
+    "race",
+    "height",
+    "weight",
+    "appearance",
+    "sexOrientationExperience",
+    "posture",
+    "unusualCharacteristics",
+    "health"
+  ],
+  social: [
+    "occupationAndAttitude",
+    "education",
+    "money",
+    "class",
+    "relationships",
+    "homeLife",
+    "religion",
+    "placeInCommunity",
+    "politics",
+    "interests"
+  ],
+  psychological: [
+    "attitudeTowardLife",
+    "moralStandard",
+    "intelligence",
+    "ambitions",
+    "frustrations",
+    "fearsAndObsessions",
+    "extrovertOrIntrovert",
+    "specialQualities",
+    "proudestAchievement",
+    "greatestSorrow",
+    "greatestShame",
+    "noticedFirst",
+    "secret",
+    "noticedLast",
+    "coreContradictions",
+    "deepestDesire"
+  ]
+};
+const CHARACTER_SKELETON_KEYS = [
+  ...CHARACTER_SKELETON_FIELDS.physical,
+  ...CHARACTER_SKELETON_FIELDS.social,
+  ...CHARACTER_SKELETON_FIELDS.psychological
+];
+const skeletonText = z.string().max(AI_ACTION_LIMITS.skeletonFieldMax);
+const characterSkeletonSchema = z.object({
+  age: skeletonText.min(1),
+  ...Object.fromEntries(
+    CHARACTER_SKELETON_KEYS.filter((k) => k !== "age").map((k) => [
+      k,
+      skeletonText.optional()
+    ])
+  )
+});
+const characterSkeletonModelSchema = z.strictObject({
+  age: skeletonText.min(1),
+  ...Object.fromEntries(
+    CHARACTER_SKELETON_KEYS.filter((k) => k !== "age").map((k) => [
+      k,
+      skeletonText.nullable()
+    ])
+  )
+});
+const SCRIPT_ELEMENT_TYPES = [
+  "action",
+  "character",
+  "parenthetical",
+  "dialogue",
+  "transition"
+];
+const scriptElementSchema = z.strictObject({
+  type: z.enum(SCRIPT_ELEMENT_TYPES),
+  text: z.string().min(1).max(AI_ACTION_LIMITS.elementTextMax)
+});
+const SCENE_SETTINGS = ["int", "ext", "intExt"];
+const sceneHeadingSchema = z.strictObject({
+  setting: z.enum(SCENE_SETTINGS),
+  location: z.string().min(1).max(AI_ACTION_LIMITS.locationMax),
+  /** "DAY", "NIGHT", "LATER" … as it would follow the dash in a heading. */
+  time: z.string().min(1).max(AI_ACTION_LIMITS.timeMax)
+});
+const generatedSceneSchema = z.strictObject({
+  heading: sceneHeadingSchema,
+  elements: z.array(scriptElementSchema).min(1).max(AI_ACTION_LIMITS.elementsPerSceneMax)
+});
+const generateCharacterSkeletonRequestSchema = z.strictObject({
+  /** A free-form paragraph describing the character. */
+  text: z.string().trim().min(1).max(AI_ACTION_LIMITS.descriptionMax),
+  /** BCP 47 tag the skeleton values are written in. Default: the language of `text`. */
+  language: z.string().max(AI_ACTION_LIMITS.languageMax).optional()
+});
+const generateCharacterSkeletonModelSchema = z.strictObject({
+  skeleton: characterSkeletonModelSchema
+});
+const generateCharacterSkeletonResultSchema = z.strictObject({
+  skeleton: characterSkeletonSchema
+});
+const generateScriptRequestSchema = z.strictObject({
+  /** The story in common language: a premise, a synopsis or a full retelling. */
+  story: z.string().trim().min(1).max(AI_ACTION_LIMITS.storyMax),
+  title: z.string().trim().max(AI_ACTION_LIMITS.titleMax).optional(),
+  /** BCP 47 tag the script is written in. Default: the language of `story`. */
+  language: z.string().max(AI_ACTION_LIMITS.languageMax).optional()
+});
+const generateScriptModelSchema = z.strictObject({
+  title: z.string().max(AI_ACTION_LIMITS.titleMax).nullable(),
+  scenes: z.array(generatedSceneSchema).min(1).max(AI_ACTION_LIMITS.scenesMax)
+});
+const generateScriptResultSchema = generateScriptModelSchema;
+const dialogueLineSchema = z.strictObject({
+  /** The caller's own id for the line, echoed back so the result maps onto it. */
+  id: z.string().min(1).max(AI_ACTION_LIMITS.idMax),
+  text: z.string().min(1).max(AI_ACTION_LIMITS.dialogueTextMax)
+});
+const polishCharacterDialogueRequestSchema = z.strictObject({
+  character: z.string().trim().min(1).max(AI_ACTION_LIMITS.characterNameMax),
+  skeleton: characterSkeletonSchema,
+  /** One character's lines, in script order. */
+  dialogues: z.array(dialogueLineSchema).min(1).max(AI_ACTION_LIMITS.dialoguesMax),
+  /** How much to change; default `medium`. */
+  intensity: z.enum(["light", "medium", "bold"]).optional(),
+  language: z.string().max(AI_ACTION_LIMITS.languageMax).optional()
+});
+const polishCharacterDialogueModelSchema = z.strictObject({
+  /** The same ids in the same order, each with the polished line. */
+  dialogues: z.array(dialogueLineSchema).min(1).max(AI_ACTION_LIMITS.dialoguesMax)
+});
+const polishCharacterDialogueResultSchema = polishCharacterDialogueModelSchema;
+const sceneCharacterSchema = z.strictObject({
+  /** The name as it appears in the script's character cues. */
+  name: z.string().trim().min(1).max(AI_ACTION_LIMITS.characterNameMax),
+  skeleton: characterSkeletonSchema
+});
+const polishSceneRequestSchema = z.strictObject({
+  scene: z.strictObject({
+    /** The scene heading as text, e.g. "INT. LAB - DAY". Context only: it is not rewritten. */
+    heading: z.string().max(AI_ACTION_LIMITS.locationMax + AI_ACTION_LIMITS.timeMax + 16).optional(),
+    elements: z.array(scriptElementSchema).min(1).max(AI_ACTION_LIMITS.sceneElementsMax)
+  }),
+  /** A skeleton for every character involved in the scene. */
+  characters: z.array(sceneCharacterSchema).min(1).max(AI_ACTION_LIMITS.sceneCharactersMax),
+  intensity: z.enum(["light", "medium", "bold"]).optional(),
+  language: z.string().max(AI_ACTION_LIMITS.languageMax).optional()
+});
+const polishSceneModelSchema = z.strictObject({
+  elements: z.array(scriptElementSchema).min(1).max(AI_ACTION_LIMITS.sceneElementsMax)
+});
+const polishSceneResultSchema = polishSceneModelSchema;
+const AI_ACTION_MODEL_SCHEMAS = {
+  "generate-character-skeleton": generateCharacterSkeletonModelSchema,
+  "generate-script": generateScriptModelSchema,
+  "polish-character-dialogue": polishCharacterDialogueModelSchema,
+  "polish-scene": polishSceneModelSchema
+};
+const AI_ACTION_REQUEST_SCHEMAS = {
+  "generate-character-skeleton": generateCharacterSkeletonRequestSchema,
+  "generate-script": generateScriptRequestSchema,
+  "polish-character-dialogue": polishCharacterDialogueRequestSchema,
+  "polish-scene": polishSceneRequestSchema
+};
 const JOB_STATUSES = [
   "queued",
   "running",
@@ -3999,6 +4203,10 @@ export {
   ACCOUNT_EXPORT_FILENAME,
   ACTIVITY_KINDS,
   ACTOR_KINDS,
+  AI_ACTIONS,
+  AI_ACTION_LIMITS,
+  AI_ACTION_MODEL_SCHEMAS,
+  AI_ACTION_REQUEST_SCHEMAS,
   AI_CONSENT_VERSION,
   AI_ENDPOINTS,
   AI_ENDPOINT_OUTPUT_SCHEMAS,
@@ -4030,6 +4238,8 @@ export {
   AUDIT_MAX_RANGE_DAYS,
   AUTOCORRECT_MAX_PAIRS,
   BATCH_WATERMARK_MAX_RECIPIENTS,
+  CHARACTER_SKELETON_FIELDS,
+  CHARACTER_SKELETON_KEYS,
   CHAT_BODY_MAX,
   CHAT_EDIT_WINDOW_MINUTES,
   CLIENT_AUTO_REASONS,
@@ -4100,6 +4310,8 @@ export {
   ROLES,
   ROLE_PERMISSIONS,
   SCENE_BATCH_MAX,
+  SCENE_SETTINGS,
+  SCRIPT_ELEMENT_TYPES,
   SEARCH_HIT_TYPES,
   SEVERITIES,
   SHARE_LINK_ACCESS,
@@ -4157,6 +4369,7 @@ export {
   adminJobKindPatchSchema,
   adminJobListQuerySchema,
   adminJobRefundSchema,
+  aiActionSchema,
   aiConsentAcceptSchema,
   aiEndpointInputSchema,
   aiEstimateRequestSchema,
@@ -4195,6 +4408,7 @@ export {
   changesQuerySchema,
   characterPacketBodySchema,
   characterPacketSchema,
+  characterSkeletonSchema,
   chatMessageCreateSchema,
   chatMessageUpdateSchema,
   chatQuerySchema,
@@ -4210,6 +4424,7 @@ export {
   defaultNotificationPrefs,
   deviceCreateSchema,
   deviceUpdateSchema,
+  dialogueLineSchema,
   dictionaryUpdateSchema,
   docSourceSchema,
   documentApplyTemplateSchema,
@@ -4241,6 +4456,13 @@ export {
   exportJobInputSchema,
   exportOptionsSchema,
   fountainQuerySchema,
+  generateCharacterSkeletonModelSchema,
+  generateCharacterSkeletonRequestSchema,
+  generateCharacterSkeletonResultSchema,
+  generateScriptModelSchema,
+  generateScriptRequestSchema,
+  generateScriptResultSchema,
+  generatedSceneSchema,
   grantUpdateSchema,
   hasPermission,
   idKind,
@@ -4282,7 +4504,13 @@ export {
   packetQuerySchema,
   parseReportOptions,
   pingPayloadSchema,
+  polishCharacterDialogueModelSchema,
+  polishCharacterDialogueRequestSchema,
+  polishCharacterDialogueResultSchema,
   polishResponseSchema,
+  polishSceneModelSchema,
+  polishSceneRequestSchema,
+  polishSceneResultSchema,
   projectBinCreateSchema,
   projectCreateSchema,
   projectDuplicateJobInputSchema,
@@ -4311,9 +4539,12 @@ export {
   roleAtLeast,
   roleChangedPayloadSchema,
   roleSchema,
+  sceneCharacterSchema,
+  sceneHeadingSchema,
   scenePacketBodySchema,
   scenePacketSchema,
   scenesBatchRequestSchema,
+  scriptElementSchema,
   searchQuerySchema,
   serverShutdownPayloadSchema,
   shareLinkCreateSchema,