@larkup/tool-video-intelligence 0.2.0

package/scripts/grant-cloud-credits.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "Usage: $0 <user-id> <monthly-source-minutes> [plan]" >&2
+  echo "Requires LARKUP_VIDEO_INTELLIGENCE_CLOUD_ENDPOINT and LARKUP_VIDEO_ADMIN_TOKEN." >&2
+  exit 64
+}
+
+USER_ID="${1:-}"
+SOURCE_MINUTES="${2:-}"
+PLAN="${3:-support-grant}"
+
+[[ -n "$USER_ID" && -n "$SOURCE_MINUTES" ]] || usage
+[[ "$USER_ID" =~ ^[A-Za-z0-9._-]{32,128}$ ]] || {
+  echo "User ID must be the generated ID shown in Installed Tools." >&2
+  exit 64
+}
+[[ "$SOURCE_MINUTES" =~ ^[0-9]+([.][0-9]+)?$ ]] || {
+  echo "Monthly source minutes must be a non-negative number." >&2
+  exit 64
+}
+[[ "$PLAN" =~ ^[A-Za-z0-9._-]{1,80}$ ]] || {
+  echo "Plan may contain only letters, numbers, dots, underscores, and hyphens." >&2
+  exit 64
+}
+
+ENDPOINT="${LARKUP_VIDEO_INTELLIGENCE_CLOUD_ENDPOINT:-}"
+ADMIN_TOKEN="${LARKUP_VIDEO_ADMIN_TOKEN:-}"
+[[ -n "$ENDPOINT" && -n "$ADMIN_TOKEN" ]] || {
+  echo "Set LARKUP_VIDEO_INTELLIGENCE_CLOUD_ENDPOINT and LARKUP_VIDEO_ADMIN_TOKEN first." >&2
+  exit 64
+}
+
+ENDPOINT="${ENDPOINT%/}"
+PAYLOAD=$(printf '{"sourceMinutesPerMonth":%s,"plan":"%s"}' "$SOURCE_MINUTES" "$PLAN")
+
+curl --fail-with-body --silent --show-error \
+  --request POST "$ENDPOINT/v1/admin/devices/$USER_ID/entitlement" \
+  --header 'Content-Type: application/json' \
+  --header "X-Larkup-Admin-Token: $ADMIN_TOKEN" \
+  --data "$PAYLOAD"
+echo

package/scripts/runtime.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const [command = 'status', ...args] = process.argv.slice(2);
+const envPath = path.join(packageDir, '.env');
+const exampleEnvPath = path.join(packageDir, '.env.example');
+
+function knownKeys() {
+  return new Set(
+    readFileSync(exampleEnvPath, 'utf8')
+      .split(/\r?\n/)
+      .map((line) => line.match(/^([A-Z][A-Z0-9_]*)=/)?.[1])
+      .filter(Boolean),
+  );
+}
+
+function readEnvValue(key) {
+  if (!existsSync(envPath)) return '';
+  const line = readFileSync(envPath, 'utf8')
+    .split(/\r?\n/)
+    .find((entry) => entry.startsWith(`${key}=`));
+  if (!line) return '';
+  const value = line.slice(key.length + 1).trim();
+  if (!value.startsWith('"')) return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function initializeEnv() {
+  if (existsSync(envPath)) return;
+  writeFileSync(envPath, readFileSync(exampleEnvPath, 'utf8'));
+  console.log('Created .env from .env.example. Add credentials with `config set KEY VALUE`.');
+}
+
+function runtimeEnvironment() {
+  if (!existsSync(envPath)) return process.env;
+  return {
+    ...process.env,
+    ...Object.fromEntries(
+      readFileSync(envPath, 'utf8')
+        .split(/\r?\n/)
+        .flatMap((line) => {
+          const match = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/);
+          if (!match) return [];
+          const [, key, raw] = match;
+          try {
+            return [[key, raw.startsWith('"') ? JSON.parse(raw) : raw]];
+          } catch {
+            return [[key, raw]];
+          }
+        }),
+    ),
+  };
+}
+
+function nativeRuntimeEnvironment() {
+  const dataDir = path.join(process.cwd(), '.larkup', 'video-intelligence');
+  return {
+    ...runtimeEnvironment(),
+    LARKUP_VIDEO_RUNTIME_KIND: 'local-process',
+    LARKUP_VIDEO_HOST: '127.0.0.1',
+    LARKUP_VIDEO_DATA_DIR: path.join(dataDir, 'data'),
+    LARKUP_VIDEO_MODEL_DIR: path.join(dataDir, 'models'),
+  };
+}
+
+function configure() {
+  const [operation = 'path', key, ...valueParts] = args;
+  if (operation === 'path') {
+    console.log(envPath);
+    return;
+  }
+  if (operation === 'init') {
+    initializeEnv();
+    return;
+  }
+  if (!key || !knownKeys().has(key)) {
+    console.error('Use a key declared in .env.example. Run `config path` to find the file.');
+    process.exitCode = 2;
+    return;
+  }
+  if (operation === 'get') {
+    console.log(readEnvValue(key));
+    return;
+  }
+  if (
+    operation !== 'set' ||
+    valueParts.length === 0 ||
+    valueParts.some((part) => /[\r\n]/.test(part))
+  ) {
+    console.error('Usage: larkup-video-intelligence config <init|path|get KEY|set KEY VALUE>');
+    process.exitCode = 2;
+    return;
+  }
+  initializeEnv();
+  const value = valueParts.join(' ');
+  const line = `${key}=${JSON.stringify(value)}`;
+  const contents = readFileSync(envPath, 'utf8');
+  const pattern = new RegExp(`^${key}=.*$`, 'm');
+  writeFileSync(
+    envPath,
+    pattern.test(contents) ? contents.replace(pattern, line) : `${contents}\n${line}\n`,
+  );
+  console.log(`Updated ${key} in .env.`);
+}
+
+if (command === 'config') {
+  configure();
+  process.exit(process.exitCode ?? 0);
+}
+
+if (command === 'start') initializeEnv();
+const accelerator = readEnvValue('LARKUP_VIDEO_ACCELERATOR').toLowerCase();
+const gpu = args.includes('--gpu') || accelerator === 'gpu' || accelerator === 'cuda';
+const compose = ['compose', '-f', path.join(packageDir, 'compose.yaml')];
+if (gpu) compose.push('-f', path.join(packageDir, 'compose.gpu.yaml'));
+
+const actions = {
+  start: [...compose, 'up', '-d', '--build', '--wait'],
+  stop: [...compose, 'down'],
+  status: [...compose, 'ps'],
+  logs: [...compose, 'logs', '-f', '--tail=200'],
+  pull: [...compose, 'pull'],
+  native: [
+    'run',
+    '--directory',
+    path.join(packageDir, 'runtime'),
+    '--extra',
+    'cpu',
+    'larkup-video-runtime',
+  ],
+};
+
+if (!(command in actions)) {
+  console.error(
+    'Usage: larkup-video-intelligence <start|stop|status|logs|pull|native> [--gpu]\\n' +
+      '       larkup-video-intelligence config <init|path|get KEY|set KEY VALUE>',
+  );
+  process.exit(2);
+}
+const result = spawnSync(command === 'native' ? 'uv' : 'docker', actions[command], {
+  stdio: 'inherit',
+  env: command === 'native' ? nativeRuntimeEnvironment() : process.env,
+});
+if (result.error) {
+  console.error(`Could not run Docker: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/scripts/validate-indexing.mjs

@@ -0,0 +1,168 @@
+import { openAsBlob } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { parseArgs } from 'node:util';
+
+const { values } = parseArgs({
+  options: {
+    endpoint: { type: 'string' },
+    runtime: { type: 'string', default: 'cloud' },
+    file: { type: 'string' },
+    output: { type: 'string' },
+    duration: { type: 'string' },
+    mode: { type: 'string', default: 'balanced' },
+    language: { type: 'string', default: 'auto' },
+    key: { type: 'string' },
+    question: { type: 'string' },
+    'range-start': { type: 'string' },
+    'range-end': { type: 'string' },
+    'max-frames': { type: 'string' },
+    continuous: { type: 'boolean', default: false },
+  },
+});
+
+if (!values.endpoint || !values.file || !values.output || !values.duration) {
+  throw new Error('--endpoint, --file, --output, and --duration are required');
+}
+if (!['fast', 'balanced', 'thorough'].includes(values.mode)) {
+  throw new Error('--mode must be fast, balanced, or thorough');
+}
+if (!values.language.trim()) {
+  throw new Error('--language must be auto or a non-empty language code');
+}
+
+const hasRange = values['range-start'] !== undefined || values['range-end'] !== undefined;
+const rangeStart = Number(values['range-start']);
+const rangeEnd = Number(values['range-end']);
+if (
+  hasRange &&
+  (!Number.isFinite(rangeStart) ||
+    !Number.isFinite(rangeEnd) ||
+    rangeStart < 0 ||
+    rangeEnd <= rangeStart)
+) {
+  throw new Error('--range-start and --range-end must form a finite increasing range');
+}
+const maxFrames = values['max-frames'] === undefined ? undefined : Number(values['max-frames']);
+if (maxFrames !== undefined && (!Number.isInteger(maxFrames) || maxFrames < 1 || maxFrames > 24)) {
+  throw new Error('--max-frames must be an integer between 1 and 24');
+}
+
+const endpoint = values.endpoint.replace(/\/$/, '');
+let apiKey = values.key || '';
+const startedAt = Date.now();
+
+async function request(path, init = {}, anonymous = false) {
+  const headers = new Headers(init.headers);
+  if (!(init.body instanceof FormData)) headers.set('Content-Type', 'application/json');
+  if (apiKey && !anonymous) headers.set('Authorization', `Bearer ${apiKey}`);
+  const response = await fetch(`${endpoint}${path}`, { ...init, headers });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(body.detail || body.error || `${path} returned HTTP ${response.status}`);
+  }
+  return body;
+}
+
+const health = await request('/v1/health');
+if (health.status !== 'ok') throw new Error('runtime health check failed');
+
+if (values.runtime === 'cloud' && !apiKey) {
+  const provisioned = await request(
+    '/v1/device-keys',
+    { method: 'POST', body: JSON.stringify({ installationId: randomUUID() }) },
+    true,
+  );
+  apiKey = provisioned.apiKey;
+}
+
+const blob = await openAsBlob(values.file, { type: 'video/mp4' });
+let upload;
+if (values.runtime === 'cloud') {
+  upload = await request('/v1/uploads', {
+    method: 'POST',
+    body: JSON.stringify({
+      fileName: 'validation-video.mp4',
+      contentType: 'video/mp4',
+      sizeBytes: blob.size,
+    }),
+  });
+  const uploaded = await fetch(upload.uploadUrl, {
+    method: 'PUT',
+    headers: upload.uploadHeaders,
+    body: blob,
+  });
+  if (!uploaded.ok) throw new Error(`source upload returned HTTP ${uploaded.status}`);
+} else {
+  const form = new FormData();
+  form.append('file', blob, 'validation-video.mp4');
+  upload = await request('/v1/uploads', { method: 'POST', body: form });
+}
+
+let job = await request('/v1/jobs', {
+  method: 'POST',
+  body: JSON.stringify({
+    source: { uploadId: upload.uploadId, durationSecs: Number(values.duration) },
+    brief: {
+      indexingMode: values.mode,
+      language: values.language.trim(),
+      goal: values.question
+        ? `Answer this question from direct timestamped source evidence: ${values.question}`
+        : 'Build a clean timestamped account of the entities, visible and spoken state history, key events, and overall source context. Use only source evidence and do not assume a content genre.',
+      expectedQuestions: values.question
+        ? [values.question]
+        : [
+            'Who or what participated?',
+            'How did the visible or spoken state change over time?',
+            'What were the key events and the final context?',
+          ],
+      ...(hasRange
+        ? {
+            importantRanges: [
+              { startSecs: rangeStart, endSecs: rangeEnd, note: 'bounded validation' },
+            ],
+            requireSemanticVision: true,
+            skipVideoEmbeddings: true,
+            continuousSequence: values.continuous,
+            ...(maxFrames === undefined ? {} : { maxFrames }),
+          }
+        : {}),
+    },
+  }),
+});
+
+let lastProgress = '';
+while (job.status === 'queued' || job.status === 'running') {
+  const progressKey = JSON.stringify(job.progress);
+  if (progressKey !== lastProgress) {
+    const elapsedSecs = Math.round((Date.now() - startedAt) / 1000);
+    process.stdout.write(
+      `${JSON.stringify({ elapsedSecs, status: job.status, ...job.progress })}\n`,
+    );
+    lastProgress = progressKey;
+  }
+  await new Promise((resolve) => setTimeout(resolve, 2_000));
+  job = await request(`/v1/jobs/${encodeURIComponent(job.id)}`);
+}
+
+if (job.status !== 'completed') throw new Error(job.error || `job ended as ${job.status}`);
+if (!job.result && job.resultUrl) {
+  const response = await fetch(job.resultUrl);
+  if (!response.ok) throw new Error(`result download returned HTTP ${response.status}`);
+  job.result = await response.json();
+}
+if (!job.result) throw new Error('completed job did not contain a result');
+
+const elapsedSecs = (Date.now() - startedAt) / 1_000;
+await writeFile(
+  values.output,
+  JSON.stringify({ runtime: values.runtime, elapsedSecs, jobId: job.id, result: job.result }, null, 2),
+  'utf8',
+);
+if (values.runtime === 'cloud') {
+  await request(`/v1/jobs/${encodeURIComponent(job.id)}/result/ack`, {
+    method: 'POST',
+    body: '{}',
+  }).catch(() => undefined);
+}
+process.stdout.write(`${JSON.stringify({ status: 'completed', elapsedSecs, output: values.output })}\n`);