@nebutra/cinema 0.2.0

package/src/director.ts

@@ -0,0 +1,50 @@
+/**
+ * Film-director composition — the ViMax pipeline form, re-expressed as a
+ * thin, fully-injected orchestrator. Every stage (write script, split shots,
+ * build cameras, infer parents, render a shot) is supplied by the caller and
+ * wired to Sailor primitives (`@nebutra/agents`, `@nebutra/reel`,
+ * `@nebutra/cinema` camera tree). This module owns only the sequencing and
+ * the cross-shot continuity guarantee — no model, no I/O.
+ */
+
+import { buildCameraTree, type Camera, type CameraParent, type CameraTree } from "./camera-tree";
+
+export interface FilmInput {
+  readonly idea: string;
+}
+
+export interface FilmSteps {
+  readonly writeScript: (idea: string) => Promise<string>;
+  readonly splitShots: (script: string) => Promise<readonly string[]>;
+  readonly buildCameras: (shots: readonly string[]) => Promise<readonly Camera[]>;
+  readonly inferParents: (cameras: readonly Camera[]) => Promise<readonly CameraParent[]>;
+  readonly renderShot: (shot: string, index: number) => Promise<{ uri: string }>;
+}
+
+export interface FilmResult {
+  readonly script: string;
+  readonly shots: readonly string[];
+  readonly cameraTree: CameraTree;
+  readonly clips: ReadonlyArray<{ shot: string; uri: string }>;
+}
+
+/**
+ * Run idea → script → shots → cameras (acyclic continuity tree) → per-shot
+ * render → assembled clip list. Shots render in narrative order so a later
+ * shot can reuse an earlier one's frames for continuity.
+ */
+export async function runFilmPipeline(input: FilmInput, steps: FilmSteps): Promise<FilmResult> {
+  const script = await steps.writeScript(input.idea);
+  const shots = await steps.splitShots(script);
+  const cameras = await steps.buildCameras(shots);
+  const cameraTree = await buildCameraTree(cameras, steps.inferParents);
+
+  const clips: Array<{ shot: string; uri: string }> = [];
+  for (let i = 0; i < shots.length; i++) {
+    const shot = shots[i] as string;
+    const { uri } = await steps.renderShot(shot, i);
+    clips.push({ shot, uri });
+  }
+
+  return { script, shots, cameraTree, clips };
+}

package/src/errors.ts

@@ -0,0 +1,13 @@
+import { CapabilityError } from "@nebutra/capability-kit";
+
+/** Every cinema failure is a CinemaError (code + actionable suggestion). */
+export class CinemaError extends CapabilityError {
+  constructor(message: string, init: { code: string; suggestion: string; cause?: unknown }) {
+    super(message, init, {
+      name: "CinemaError",
+      emptySuggestionFallback:
+        "No suggestion was provided. This is a bug in @nebutra/cinema — " +
+        "report it with the failing stage.",
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @nebutra/cinema — agentic film-production IP absorbed from a research
+ * video pipeline, re-expressed clean-room as pure, dependency-injected
+ * orchestration on top of Sailor primitives.
+ *
+ * SKIP (reused, not re-implemented): typed media DAG + script→shots split
+ * (`@nebutra/reel`), agent loop (`@nebutra/agent-runtime`), LLM + image/video
+ * generation registry (`@nebutra/agents`), acyclic guard
+ * (`@nebutra/graph-model`), errors/cli (`@nebutra/capability-kit`).
+ *
+ * PORT (this package — the differentiated IP): camera-continuity tree,
+ * consistency-ranked best-frame selection, novel→scene segmentation, and the
+ * film-director composition. Every model/IO touchpoint is injected, so this
+ * is multi-tenant-agnostic and fully unit-testable.
+ */
+
+export {
+  type BestFrame,
+  type FrameCandidate,
+  type RankFrames,
+  selectBestFrame,
+} from "./best-frame";
+export {
+  buildCameraTree,
+  type Camera,
+  type CameraParent,
+  type CameraTree,
+  type InferParents,
+  resolveContinuityChain,
+} from "./camera-tree";
+export {
+  type FilmInput,
+  type FilmResult,
+  type FilmSteps,
+  runFilmPipeline,
+} from "./director";
+export { CinemaError } from "./errors";
+export { type CompleteFn, compressNovel, extractScenes } from "./novel-segment";

package/src/novel-segment.ts

@@ -0,0 +1,59 @@
+/**
+ * Novel → compressed chunks → scene units — ViMax-distinct IP, re-expressed.
+ *
+ * Long-form adaptation: compress chapters (preserving plot/character) then
+ * segment into filmable scenes. Both steps are model calls — injected via a
+ * `CompleteFn` (the same injection shape `@nebutra/reel/storyboard` uses, so
+ * callers wire it to `@nebutra/agents` once). RAG retrieval, when used, is
+ * supplied by `@nebutra/knowledge-rag` through the same injection — not a
+ * hard dependency here.
+ */
+
+import { CinemaError } from "./errors";
+
+/** Injected model call: prompt in, completion text out. */
+export type CompleteFn = (prompt: string) => Promise<string>;
+
+/** Compress each chunk independently; order is preserved. */
+export async function compressNovel(
+  chunks: readonly string[],
+  complete: CompleteFn,
+): Promise<string[]> {
+  return Promise.all(
+    chunks.map((chunk) =>
+      complete(
+        `Compress this passage, preserving plot, character and emotional ` +
+          `beats; output prose only:\n\n${chunk}`,
+      ),
+    ),
+  );
+}
+
+/**
+ * Extract ordered scene units from compressed text. The model is asked for a
+ * JSON array of scene strings; parsing tolerates surrounding prose but a
+ * non-array response is a hard error (a silent empty list would drop story).
+ */
+export async function extractScenes(compressed: string, complete: CompleteFn): Promise<string[]> {
+  const raw = await complete(
+    `Split the following into a JSON array of self-contained, filmable ` +
+      `scene descriptions in narrative order. Output ONLY the array:\n\n${compressed}`,
+  );
+  const match = raw.match(/\[[\s\S]*\]/);
+  if (match) {
+    try {
+      const parsed: unknown = JSON.parse(match[0]);
+      if (Array.isArray(parsed) && parsed.every((s) => typeof s === "string")) {
+        return parsed as string[];
+      }
+    } catch {
+      // fall through to the structured error below
+    }
+  }
+  throw new CinemaError("Scene extraction did not return a JSON string array.", {
+    code: "CINEMA_SCENE_PARSE",
+    suggestion:
+      "Constrain the model to emit a JSON array of strings (use a schema / " +
+      "response-format), or retry — output was not parseable.",
+  });
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "incremental": false
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  target: "es2022",
+});