@nebutra/cinema 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @nebutra/cinema
 
+## 0.2.4
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @nebutra/capability-kit@2.0.0
+  - @nebutra/graph-model@2.0.0
+
 ## 0.2.2
 
 ### Patch Changes

package/package.json

@@ -1,24 +1,30 @@
 {
   "name": "@nebutra/cinema",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Agentic film-production IP: acyclic camera-continuity tree, consistency-ranked best-frame selection, novel→scene/event segmentation, film-director composition. Pure + dependency-injected; sits on reel/agents/graph-model.",
   "private": false,
   "license": "MIT",
   "type": "module",
   "nebutra": {
+    "status": "wip",
+    "graph": "labs",
     "featureId": "cinema",
     "category": "ai",
     "surface": "product-orchestration",
     "summary": "Multi-agent film-production orchestration over the reel media graph"
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
   },
   "dependencies": {
-    "@nebutra/capability-kit": "0.2.2",
-    "@nebutra/graph-model": "0.2.2"
+    "@nebutra/capability-kit": "2.0.0",
+    "@nebutra/graph-model": "2.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
@@ -38,6 +44,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",

package/.turbo/turbo-build.log

@@ -1,17 +0,0 @@
-
-> @nebutra/cinema@0.2.2 build /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/cinema
-> tsup
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/cinema/tsup.config.ts
-CLI Target: es2022
-CLI Cleaning output folder
-ESM Build start
-ESM dist/index.js     4.37 KB
-ESM dist/index.js.map 12.98 KB
-ESM ⚡️ Build success in 13ms
-DTS Build start
-DTS ⚡️ Build success in 2786ms
-DTS dist/index.d.ts 5.90 KB

package/.turbo/turbo-test.log

@@ -1,14 +0,0 @@
-
-> @nebutra/cinema@0.2.1 test /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/cinema
-> vitest run
-
-
- RUN  v4.1.4 /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/cinema
-
- ✓ src/__tests__/cinema.test.ts (11 tests) 10ms
-
- Test Files  1 passed (1)
-      Tests  11 passed (11)
-   Start at  09:38:38
-   Duration  641ms (transform 271ms, setup 0ms, import 301ms, tests 10ms, environment 0ms)
-

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @nebutra/cinema@0.2.2 typecheck /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/cinema
-> tsc --noEmit
-

package/src/__tests__/cinema.test.ts

@@ -1,141 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { selectBestFrame } from "../best-frame";
-import { buildCameraTree, resolveContinuityChain } from "../camera-tree";
-import { runFilmPipeline } from "../director";
-import { CinemaError } from "../errors";
-import { compressNovel, extractScenes } from "../novel-segment";
-
-const cams = [
-  { id: "c0", shotIds: ["s0", "s1"] },
-  { id: "c1", shotIds: ["s2"] },
-  { id: "c2", shotIds: ["s3"] },
-];
-
-describe("buildCameraTree", () => {
-  it("builds an acyclic tree with the first camera as root", async () => {
-    const tree = await buildCameraTree(cams, async () => [
-      { cameraId: "c0", parentCameraId: null, parentShotId: null, fullyCovers: true },
-      { cameraId: "c1", parentCameraId: "c0", parentShotId: "s0", fullyCovers: true },
-      { cameraId: "c2", parentCameraId: "c1", parentShotId: "s2", fullyCovers: false },
-    ]);
-    expect(tree.rootId).toBe("c0");
-    expect(tree.parentOf("c1")).toBe("c0");
-  });
-
-  it("rejects a cyclic parent assignment (graph-model guard)", async () => {
-    await expect(
-      buildCameraTree(cams, async () => [
-        { cameraId: "c0", parentCameraId: "c2", parentShotId: "s3", fullyCovers: true },
-        { cameraId: "c1", parentCameraId: "c0", parentShotId: "s0", fullyCovers: true },
-        { cameraId: "c2", parentCameraId: "c1", parentShotId: "s2", fullyCovers: true },
-      ]),
-    ).rejects.toBeInstanceOf(CinemaError);
-  });
-
-  it("rejects when the first camera is not a root", async () => {
-    await expect(
-      buildCameraTree(cams, async () => [
-        { cameraId: "c0", parentCameraId: "c1", parentShotId: "s2", fullyCovers: true },
-        { cameraId: "c1", parentCameraId: null, parentShotId: null, fullyCovers: true },
-        { cameraId: "c2", parentCameraId: "c1", parentShotId: "s2", fullyCovers: true },
-      ]),
-    ).rejects.toThrow(/root/i);
-  });
-
-  it("resolveContinuityChain returns the root→node inheritance order", async () => {
-    const tree = await buildCameraTree(cams, async () => [
-      { cameraId: "c0", parentCameraId: null, parentShotId: null, fullyCovers: true },
-      { cameraId: "c1", parentCameraId: "c0", parentShotId: "s0", fullyCovers: true },
-      { cameraId: "c2", parentCameraId: "c1", parentShotId: "s2", fullyCovers: true },
-    ]);
-    expect(resolveContinuityChain(tree, "c2")).toEqual(["c0", "c1", "c2"]);
-    expect(resolveContinuityChain(tree, "c0")).toEqual(["c0"]);
-  });
-});
-
-describe("selectBestFrame", () => {
-  const cands = [
-    { id: "a", uri: "data:a" },
-    { id: "b", uri: "data:b" },
-  ];
-  it("returns the ranked best and its reason", async () => {
-    const r = await selectBestFrame(cands, "Alice on the left", async () => ({
-      bestId: "b",
-      reason: "best character consistency",
-    }));
-    expect(r.best.id).toBe("b");
-    expect(r.reason).toMatch(/consistency/);
-  });
-  it("throws CinemaError on empty candidates", async () => {
-    await expect(
-      selectBestFrame([], "x", async () => ({ bestId: "", reason: "" })),
-    ).rejects.toBeInstanceOf(CinemaError);
-  });
-  it("throws when the ranker picks an unknown id", async () => {
-    await expect(
-      selectBestFrame(cands, "x", async () => ({ bestId: "zzz", reason: "" })),
-    ).rejects.toThrow(/not among/i);
-  });
-});
-
-describe("novel segmentation", () => {
-  it("compressNovel preserves chunk order", async () => {
-    const out = await compressNovel(["AAA", "BBB"], async (p) => `c:${p.slice(-3)}`);
-    expect(out).toEqual(["c:AAA", "c:BBB"]);
-  });
-  it("extractScenes parses a JSON array, tolerating prose wrapping", async () => {
-    const scenes = await extractScenes("novel", async () => 'noise ["scene 1","scene 2"] tail');
-    expect(scenes).toEqual(["scene 1", "scene 2"]);
-  });
-  it("extractScenes throws CinemaError on unparseable output", async () => {
-    await expect(extractScenes("x", async () => "no array here")).rejects.toBeInstanceOf(
-      CinemaError,
-    );
-  });
-});
-
-describe("runFilmPipeline", () => {
-  it("threads idea→script→shots→cameras→frames in order and returns the assembly", async () => {
-    const calls: string[] = [];
-    const result = await runFilmPipeline(
-      { idea: "a dog learns to fly" },
-      {
-        writeScript: async (idea) => {
-          calls.push("script");
-          return `SCRIPT(${idea})`;
-        },
-        splitShots: async (script) => {
-          calls.push("shots");
-          return [`${script}#0`, `${script}#1`];
-        },
-        buildCameras: async (shots) => {
-          calls.push("cameras");
-          return shots.map((_, i) => ({ id: `c${i}`, shotIds: [`s${i}`] }));
-        },
-        inferParents: async (cameras) =>
-          cameras.map((c, i) => ({
-            cameraId: c.id,
-            parentCameraId: i === 0 ? null : `c${i - 1}`,
-            parentShotId: i === 0 ? null : `s${i - 1}`,
-            fullyCovers: true,
-          })),
-        renderShot: async (shot) => {
-          calls.push(`render:${shot}`);
-          return { uri: `mp4:${shot}` };
-        },
-      },
-    );
-    expect(calls).toEqual([
-      "script",
-      "shots",
-      "cameras",
-      "render:SCRIPT(a dog learns to fly)#0",
-      "render:SCRIPT(a dog learns to fly)#1",
-    ]);
-    expect(result.clips.map((c) => c.uri)).toEqual([
-      "mp4:SCRIPT(a dog learns to fly)#0",
-      "mp4:SCRIPT(a dog learns to fly)#1",
-    ]);
-    expect(result.cameraTree.rootId).toBe("c0");
-  });
-});

package/src/best-frame.ts

@@ -1,55 +0,0 @@
-/**
- * Consistency-ranked best-frame selection — ViMax-distinct IP, re-expressed.
- *
- * Generate N candidate frames, then have an MLLM rank them for character /
- * spatial / semantic consistency against the target description and pick the
- * best. The ranking is injected (a model call in production); this module
- * owns only the orchestration + validation invariants.
- */
-
-import { CinemaError } from "./errors";
-
-export interface FrameCandidate {
-  readonly id: string;
-  readonly uri: string;
-}
-
-/** Injected ranker: returns the winning candidate id + a human reason. */
-export type RankFrames = (
-  candidates: readonly FrameCandidate[],
-  targetDescription: string,
-) => Promise<{ bestId: string; reason: string }>;
-
-export interface BestFrame {
-  readonly best: FrameCandidate;
-  readonly reason: string;
-}
-
-/**
- * Select the most consistent frame. Throws if there are no candidates or if
- * the ranker returns an id that is not among them (a model contract breach
- * must never silently pick the wrong frame).
- */
-export async function selectBestFrame(
-  candidates: readonly FrameCandidate[],
-  targetDescription: string,
-  rank: RankFrames,
-): Promise<BestFrame> {
-  if (candidates.length === 0) {
-    throw new CinemaError("No candidate frames to select from.", {
-      code: "CINEMA_NO_CANDIDATES",
-      suggestion: "Generate at least one candidate frame before ranking.",
-    });
-  }
-  const { bestId, reason } = await rank(candidates, targetDescription);
-  const best = candidates.find((c) => c.id === bestId);
-  if (!best) {
-    throw new CinemaError(`Ranker chose "${bestId}", which is not among the candidates.`, {
-      code: "CINEMA_RANKER_CONTRACT",
-      suggestion:
-        "The injected ranker must return one of the provided candidate ids; " +
-        "constrain its output schema.",
-    });
-  }
-  return { best, reason };
-}

package/src/camera-tree.ts

@@ -1,103 +0,0 @@
-/**
- * Camera-continuity tree — the ViMax-distinct IP, re-expressed.
- *
- * A film is shot by multiple cameras; a parent camera's footage encompasses
- * its children's, so a child shot can inherit the parent's frames for
- * temporal/character continuity. The parent inference itself is a model call
- * (injected — never bound to a provider here). The structural invariants are
- * enforced locally with the neutral `@nebutra/graph-model` acyclic guard
- * (governance: reuse, don't re-implement cycle detection).
- */
-
-import type { GraphEdge } from "@nebutra/graph-model";
-import { wouldCreateCycle } from "@nebutra/graph-model";
-import { CinemaError } from "./errors";
-
-export interface Camera {
-  readonly id: string;
-  readonly shotIds: readonly string[];
-}
-
-export interface CameraParent {
-  readonly cameraId: string;
-  /** Null = this camera is a root. */
-  readonly parentCameraId: string | null;
-  /** Which parent shot subsumes this camera (null at root). */
-  readonly parentShotId: string | null;
-  readonly fullyCovers: boolean;
-  readonly missingInfo?: string;
-}
-
-/** Injected: infer each camera's parent (a model call in production). */
-export type InferParents = (cameras: readonly Camera[]) => Promise<readonly CameraParent[]>;
-
-export interface CameraTree {
-  readonly rootId: string;
-  readonly cameras: readonly Camera[];
-  /** Parent camera id, or null for the root. */
-  parentOf(cameraId: string): string | null;
-}
-
-/**
- * Build the camera tree: infer parents, enforce that the first camera is the
- * root, and that the parent relation is acyclic (a parent's footage cannot
- * transitively depend on its descendant).
- */
-export async function buildCameraTree(
-  cameras: readonly Camera[],
-  infer: InferParents,
-): Promise<CameraTree> {
-  if (cameras.length === 0) {
-    throw new CinemaError("Cannot build a camera tree from zero cameras.", {
-      code: "CINEMA_NO_CAMERAS",
-      suggestion: "Pass at least one camera (the root).",
-    });
-  }
-
-  const parents = await infer(cameras);
-  const parentById = new Map<string, string | null>();
-  for (const p of parents) parentById.set(p.cameraId, p.parentCameraId);
-
-  const firstId = cameras[0]?.id;
-  if (parentById.get(firstId as string)) {
-    throw new CinemaError(`The first camera "${firstId}" must be the tree root.`, {
-      code: "CINEMA_BAD_ROOT",
-      suggestion: "Ensure the inference returns parentCameraId=null for the first camera.",
-    });
-  }
-
-  // Acyclic guard via graph-model: add parent→child edges incrementally.
-  const edges: GraphEdge[] = [];
-  for (const p of parents) {
-    if (p.parentCameraId == null) continue;
-    if (wouldCreateCycle(edges, p.parentCameraId, p.cameraId)) {
-      throw new CinemaError(`Camera parent assignment is cyclic at "${p.cameraId}".`, {
-        code: "CINEMA_CYCLIC_TREE",
-        suggestion:
-          "A parent camera must not transitively depend on its descendant; " +
-          "re-infer parents or break the cycle.",
-      });
-    }
-    edges.push({ from: p.parentCameraId, to: p.cameraId });
-  }
-
-  return {
-    rootId: firstId as string,
-    cameras,
-    parentOf: (id) => parentById.get(id) ?? null,
-  };
-}
-
-/** Root→node camera order — the frame-inheritance chain for continuity. */
-export function resolveContinuityChain(tree: CameraTree, cameraId: string): string[] {
-  const chain: string[] = [];
-  let cur: string | null = cameraId;
-  const seen = new Set<string>();
-  while (cur) {
-    if (seen.has(cur)) break; // defensive; tree is acyclic by construction
-    seen.add(cur);
-    chain.push(cur);
-    cur = tree.parentOf(cur);
-  }
-  return chain.reverse();
-}

package/src/director.ts

@@ -1,50 +0,0 @@
-/**
- * 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

@@ -1,13 +0,0 @@
-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

@@ -1,38 +0,0 @@
-/**
- * @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

@@ -1,59 +0,0 @@
-/**
- * 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

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

package/tsup.config.ts

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