@codesoul-co/hypha-tools / media

• Package index: @codesoul-co/hypha-tools
• Source: packages/tools/src/media.ts
• Exports: 18

Using this module

Use the Media module for declaring text, image, audio, and binary Tool inputs and outputs. It exports 4 constants, 2 functions, 10 interfaces, 2 types.

Import from the package entrypoint

import {
  genericOcrInputJsonSchema,
  genericVideoSourceInputJsonSchema,
  ocrRequestSchema,
  videoSourceRequestSchema,
  createOcrToolSpec,
  createVideoSourceToolSpec,
} from '@codesoul-co/hypha-tools';

import type {
  OcrBlock,
  OcrBoundingBox,
  OcrPage,
  OcrProvider,
  OcrRequest,
  OcrResult,
  VideoSourceEpisode,
  VideoSourcePreview,
} from '@codesoul-co/hypha-tools';

// The complete export list is documented below.

Usage patterns

• Use the 12 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.
• The module exposes 2 functions as direct operation entrypoints. Every overload, required/optional parameter, and return type is documented below.
• The 4 constant/enum exports provide stable values, schemas, definitions, or defaults. Reuse these exports instead of copying internal values into an application.

Runtime validation example

import { ocrRequestSchema } from '@codesoul-co/hypha-tools';

declare function loadExternalInput(): unknown;
const input: unknown = loadExternalInput();
const parsed = ocrRequestSchema.parse(input);

Parse untrusted configuration, network, or persisted input with the runtime schema before passing it to functions or classes that expect a validated contract.

Public exports

Symbol	Kind	Signature	Description
genericOcrInputJsonSchema	constant	const genericOcrInputJsonSchema: JsonSchema	JSON Schema for Generic Ocr Input.
genericVideoSourceInputJsonSchema	constant	const genericVideoSourceInputJsonSchema: JsonSchema	JSON Schema for Generic Video Source Input.
ocrRequestSchema	constant	const ocrRequestSchema: z.ZodObject<{ source: z.ZodType<OcrInputSource, z.ZodTypeDef, OcrInputSource>; languages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; pageRange: z.ZodOptional<z.ZodObject<{ start: z.ZodOptional<z.ZodNumber>; end: z.ZodOptional<z.ZodNumber>; }, "strip", z.ZodTypeAny, { start?: number | undefined; end?: number | undefined; }, { start?: number | undefined; end?: number | undefined; }>>; fe...	Runtime schema for Ocr Request.
videoSourceRequestSchema	constant	const videoSourceRequestSchema: z.ZodObject<{ url: z.ZodString; titleHint: z.ZodOptional<z.ZodString>; locale: z.ZodOptional<z.ZodString>; includeEpisodes: z.ZodOptional<z.ZodBoolean>; includeCaptions: z.ZodOptional<z.ZodBoolean>; providerHint: z.ZodOptional<z.ZodString>; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strip", z.ZodTypeAny, { url: string; metadata?: Record<string, unknown> | u...	Runtime schema for Video Source Request.
createOcrToolSpec	function	createOcrToolSpec(overrides?: Partial<ToolSpec>): ToolSpec	Create Ocr Tool Spec function with 1 public call signature; parameters and return types are listed below.
createVideoSourceToolSpec	function	createVideoSourceToolSpec(overrides?: Partial<ToolSpec>): ToolSpec	Create Video Source Tool Spec function with 1 public call signature; parameters and return types are listed below.
OcrBlock	interface	interface OcrBlock	Ocr Block interface with 6 public fields or methods.
OcrBoundingBox	interface	interface OcrBoundingBox	Ocr Bounding Box interface with 5 public fields or methods.
OcrPage	interface	interface OcrPage	Ocr Page interface with 7 public fields or methods.
OcrProvider	interface	interface OcrProvider	Ocr Provider interface with 3 public fields or methods.
OcrRequest	interface	interface OcrRequest	Ocr Request interface with 7 public fields or methods.
OcrResult	interface	interface OcrResult	Ocr Result interface with 10 public fields or methods.
VideoSourceEpisode	interface	interface VideoSourceEpisode	Video Source Episode interface with 8 public fields or methods.
VideoSourcePreview	interface	interface VideoSourcePreview	Video Source Preview interface with 15 public fields or methods.
VideoSourceProvider	interface	interface VideoSourceProvider	Video Source Provider interface with 4 public fields or methods.
VideoSourceRequest	interface	interface VideoSourceRequest	Video Source Request interface with 7 public fields or methods.
OcrInputSource	type	type OcrInputSource = { type: 'artifact'; artifactRef: string; mimeType?: string; fileName?: string; } | { type: 'url'; url: string; mimeType?: string; fileName?: string; } | { type: 'inline'; dataBase64: string; mimeType: string; fileName?: string; } | { type: 'text'; text: string; fileName?: string; }	Public type alias for Ocr Input Source; the declaration contains its complete type expression.
VideoSourceKind	type	type VideoSourceKind = 'video' | 'playlist' | 'collection' | 'live' | 'unknown'	Public type alias for Video Source Kind; the declaration contains its complete type expression.

genericOcrInputJsonSchema

JSON Schema for Generic Ocr Input.

• Kind: constant
• Import: import { genericOcrInputJsonSchema } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export declare const genericOcrInputJsonSchema: JsonSchema;

genericVideoSourceInputJsonSchema

JSON Schema for Generic Video Source Input.

• Kind: constant
• Import: import { genericVideoSourceInputJsonSchema } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export declare const genericVideoSourceInputJsonSchema: JsonSchema;

ocrRequestSchema

Runtime schema for Ocr Request.

• Kind: constant
• Import: import { ocrRequestSchema } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export declare const ocrRequestSchema: z.ZodObject<{ source: z.ZodType<OcrInputSource, z.ZodTypeDef, OcrInputSource>; languages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; pageRange: z.ZodOptional<z.ZodObject<{ start: z.ZodOptional<z.ZodNumber>; end: z.ZodOptional<z.ZodNumber>; }, "strip", z.ZodTypeAny, { start?: number | undefined; end?: number | undefined; }, { start?: number | undefined; end?: number | undefined; }>>; features: z.ZodOptional<z.ZodArray<z.ZodEnum<["text", "layout", "tables", "formulas"]>, "many">>; output: z.ZodOptional<z.ZodObject<{ includeBlocks: z.ZodOptional<z.ZodBoolean>; includeConfidence: z.ZodOptional<z.ZodBoolean>; artifactize: z.ZodOptional<z.ZodBoolean>; }, "strip", z.ZodTypeAny, { includeBlocks?: boolean | undefined; includeConfidence?: boolean | undefined; artifactize?: boolean | undefined; }, { includeBlocks?: boolean | undefined; includeConfidence?: boolean | undefined; artifactize?: boolean | undefined; }>>; providerHint: z.ZodOptional<z.ZodString>; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strip", z.ZodTypeAny, { source: OcrInputSource; metadata?: Record<string, unknown> | undefined; output?: { includeBlocks?: boolean | undefined; includeConfidence?: boolean | undefined; artifactize?: boolean | undefined; } | undefined; languages?: string[] | undefined; pageRange?: { start?: number | undefined; end?: number | undefined; } | undefined; features?: ("text" | "layout" | "tables" | "formulas")[] | undefined; providerHint?: string | undefined; }, { source: OcrInputSource; metadata?: Record<string, unknown> | undefined; output?: { includeBlocks?: boolean | undefined; includeConfidence?: boolean | undefined; artifactize?: boolean | undefined; } | undefined; languages?: string[] | undefined; pageRange?: { start?: number | undefined; end?: number | undefined; } | undefined; features?: ("text" | "layout" | "tables" | "formulas")[] | undefined; providerHint?: string | undefined; }>;

videoSourceRequestSchema

Runtime schema for Video Source Request.

• Kind: constant
• Import: import { videoSourceRequestSchema } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export declare const videoSourceRequestSchema: z.ZodObject<{ url: z.ZodString; titleHint: z.ZodOptional<z.ZodString>; locale: z.ZodOptional<z.ZodString>; includeEpisodes: z.ZodOptional<z.ZodBoolean>; includeCaptions: z.ZodOptional<z.ZodBoolean>; providerHint: z.ZodOptional<z.ZodString>; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strip", z.ZodTypeAny, { url: string; metadata?: Record<string, unknown> | undefined; providerHint?: string | undefined; titleHint?: string | undefined; locale?: string | undefined; includeEpisodes?: boolean | undefined; includeCaptions?: boolean | undefined; }, { url: string; metadata?: Record<string, unknown> | undefined; providerHint?: string | undefined; titleHint?: string | undefined; locale?: string | undefined; includeEpisodes?: boolean | undefined; includeCaptions?: boolean | undefined; }>;

createOcrToolSpec

Create Ocr Tool Spec function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { createOcrToolSpec } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export declare function createOcrToolSpec(overrides?: Partial<ToolSpec>): ToolSpec;

Call signature

createOcrToolSpec(overrides?: Partial<ToolSpec>): ToolSpec

Parameters

Parameter	Type	Required	Description
overrides	Partial<ToolSpec>	No	Optional parameter; accepted values are defined by the type column.

Returns

• Type: ToolSpec
• Description: The return contract is defined by the type shown above.

createVideoSourceToolSpec

Create Video Source Tool Spec function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { createVideoSourceToolSpec } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export declare function createVideoSourceToolSpec(overrides?: Partial<ToolSpec>): ToolSpec;

Call signature

createVideoSourceToolSpec(overrides?: Partial<ToolSpec>): ToolSpec

Parameters

Parameter	Type	Required	Description
overrides	Partial<ToolSpec>	No	Optional parameter; accepted values are defined by the type column.

Returns

• Type: ToolSpec
• Description: The return contract is defined by the type shown above.

OcrBlock

Ocr Block interface with 6 public fields or methods.

• Kind: interface
• Import: import type { OcrBlock } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface OcrBlock {
    id?: string;
    type: 'text' | 'title' | 'list' | 'table' | 'formula' | 'image' | 'unknown';
    text?: string;
    confidence?: number;
    boundingBox?: OcrBoundingBox;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
boundingBox	property	boundingBox?: OcrBoundingBox	Public property; its type, readonly modifier and optionality are shown in the signature.
confidence	property	confidence?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
text	property	text?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
type	property	type: "unknown" | "image" | "table" | "list" | "text" | "title" | "formula"	Public property; its type, readonly modifier and optionality are shown in the signature.

OcrBoundingBox

Ocr Bounding Box interface with 5 public fields or methods.

• Kind: interface
• Import: import type { OcrBoundingBox } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface OcrBoundingBox {
    x: number;
    y: number;
    width: number;
    height: number;
    unit?: 'pixel' | 'normalized' | 'point';
}

Contract members

Member	Kind	Signature	Description
height	property	height: number	Public property; its type, readonly modifier and optionality are shown in the signature.
unit	property	unit?: "pixel" | "normalized" | "point"	Public property; its type, readonly modifier and optionality are shown in the signature.
width	property	width: number	Public property; its type, readonly modifier and optionality are shown in the signature.
x	property	x: number	Public property; its type, readonly modifier and optionality are shown in the signature.
y	property	y: number	Public property; its type, readonly modifier and optionality are shown in the signature.

OcrPage

Ocr Page interface with 7 public fields or methods.

• Kind: interface
• Import: import type { OcrPage } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface OcrPage {
    pageNumber: number;
    text: string;
    confidence?: number;
    width?: number;
    height?: number;
    blocks?: OcrBlock[];
    artifactRefs?: string[];
}

Contract members

Member	Kind	Signature	Description
artifactRefs	property	artifactRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
blocks	property	blocks?: OcrBlock[]	Public property; its type, readonly modifier and optionality are shown in the signature.
confidence	property	confidence?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
height	property	height?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
pageNumber	property	pageNumber: number	Public property; its type, readonly modifier and optionality are shown in the signature.
text	property	text: string	Public property; its type, readonly modifier and optionality are shown in the signature.
width	property	width?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

OcrProvider

Ocr Provider interface with 3 public fields or methods.

• Kind: interface
• Import: import type { OcrProvider } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface OcrProvider {
    readonly id: string;
    recognize(request: OcrRequest, context?: ToolCallContext): Promise<OcrResult>;
    health?(): Promise<{
        status: 'healthy' | 'degraded' | 'unavailable';
        message?: string;
    }>;
}

Contract members

Member	Kind	Signature	Description
health	method	health?(): Promise<{ status: "healthy" | "degraded" | "unavailable"; message?: string; }>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
recognize	method	recognize(request: OcrRequest, context?: ToolCallContext): Promise<OcrResult>	Public method; parameters and return type are shown in the signature.

OcrRequest

Ocr Request interface with 7 public fields or methods.

• Kind: interface
• Import: import type { OcrRequest } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface OcrRequest {
    source: OcrInputSource;
    languages?: string[];
    pageRange?: {
        start?: number;
        end?: number;
    };
    features?: Array<'text' | 'layout' | 'tables' | 'formulas'>;
    output?: {
        includeBlocks?: boolean;
        includeConfidence?: boolean;
        artifactize?: boolean;
    };
    providerHint?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
features	property	features?: ("text" | "layout" | "tables" | "formulas")[]	Public property; its type, readonly modifier and optionality are shown in the signature.
languages	property	languages?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
output	property	output?: { includeBlocks?: boolean; includeConfidence?: boolean; artifactize?: boolean; }	Public property; its type, readonly modifier and optionality are shown in the signature.
pageRange	property	pageRange?: { start?: number; end?: number; }	Public property; its type, readonly modifier and optionality are shown in the signature.
providerHint	property	providerHint?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	source: OcrInputSource	Public property; its type, readonly modifier and optionality are shown in the signature.

OcrResult

Ocr Result interface with 10 public fields or methods.

• Kind: interface
• Import: import type { OcrResult } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface OcrResult {
    status: 'completed' | 'partial' | 'failed';
    provider: string;
    providerVersion?: string;
    text?: string;
    pages: OcrPage[];
    detectedLanguages?: string[];
    artifactRefs?: string[];
    warnings?: string[];
    error?: {
        code: string;
        message: string;
        retryable?: boolean;
    };
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
artifactRefs	property	artifactRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
detectedLanguages	property	detectedLanguages?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
error	property	error?: { code: string; message: string; retryable?: boolean; }	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
pages	property	pages: OcrPage[]	Public property; its type, readonly modifier and optionality are shown in the signature.
provider	property	provider: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerVersion	property	providerVersion?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: "completed" | "failed" | "partial"	Public property; its type, readonly modifier and optionality are shown in the signature.
text	property	text?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
warnings	property	warnings?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.

VideoSourceEpisode

Video Source Episode interface with 8 public fields or methods.

• Kind: interface
• Import: import type { VideoSourceEpisode } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface VideoSourceEpisode {
    id?: string;
    title: string;
    order: number;
    durationSeconds?: number;
    url?: string;
    thumbnailUrl?: string;
    captionRefs?: string[];
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
captionRefs	property	captionRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
durationSeconds	property	durationSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
order	property	order: number	Public property; its type, readonly modifier and optionality are shown in the signature.
thumbnailUrl	property	thumbnailUrl?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
title	property	title: string	Public property; its type, readonly modifier and optionality are shown in the signature.
url	property	url?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

VideoSourcePreview

Video Source Preview interface with 15 public fields or methods.

• Kind: interface
• Import: import type { VideoSourcePreview } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface VideoSourcePreview {
    provider: string;
    sourceKind: VideoSourceKind;
    sourceId?: string;
    canonicalUrl: string;
    title: string;
    description?: string;
    author?: string;
    durationSeconds?: number;
    publishedAt?: string;
    thumbnailUrl?: string;
    episodes: VideoSourceEpisode[];
    parsedAt: string;
    warnings?: string[];
    manualEntryRequired?: boolean;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
author	property	author?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
canonicalUrl	property	canonicalUrl: string	Public property; its type, readonly modifier and optionality are shown in the signature.
description	property	description?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
durationSeconds	property	durationSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
episodes	property	episodes: VideoSourceEpisode[]	Public property; its type, readonly modifier and optionality are shown in the signature.
manualEntryRequired	property	manualEntryRequired?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
parsedAt	property	parsedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
provider	property	provider: string	Public property; its type, readonly modifier and optionality are shown in the signature.
publishedAt	property	publishedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sourceId	property	sourceId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sourceKind	property	sourceKind: VideoSourceKind	Public property; its type, readonly modifier and optionality are shown in the signature.
thumbnailUrl	property	thumbnailUrl?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
title	property	title: string	Public property; its type, readonly modifier and optionality are shown in the signature.
warnings	property	warnings?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.

VideoSourceProvider

Video Source Provider interface with 4 public fields or methods.

• Kind: interface
• Import: import type { VideoSourceProvider } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface VideoSourceProvider {
    readonly id: string;
    supports(url: string): boolean | Promise<boolean>;
    preview(request: VideoSourceRequest, context?: ToolCallContext): Promise<VideoSourcePreview>;
    health?(): Promise<{
        status: 'healthy' | 'degraded' | 'unavailable';
        message?: string;
    }>;
}

Contract members

Member	Kind	Signature	Description
health	method	health?(): Promise<{ status: "healthy" | "degraded" | "unavailable"; message?: string; }>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
preview	method	preview(request: VideoSourceRequest, context?: ToolCallContext): Promise<VideoSourcePreview>	Public method; parameters and return type are shown in the signature.
supports	method	supports(url: string): boolean | Promise<boolean>	Public method; parameters and return type are shown in the signature.

VideoSourceRequest

Video Source Request interface with 7 public fields or methods.

• Kind: interface
• Import: import type { VideoSourceRequest } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export interface VideoSourceRequest {
    url: string;
    titleHint?: string;
    locale?: string;
    includeEpisodes?: boolean;
    includeCaptions?: boolean;
    providerHint?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
includeCaptions	property	includeCaptions?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
includeEpisodes	property	includeEpisodes?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
locale	property	locale?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
providerHint	property	providerHint?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
titleHint	property	titleHint?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
url	property	url: string	Public property; its type, readonly modifier and optionality are shown in the signature.

OcrInputSource

Public type alias for Ocr Input Source; the declaration contains its complete type expression.

• Kind: type
• Import: import type { OcrInputSource } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export type OcrInputSource = {
    type: 'artifact';
    artifactRef: string;
    mimeType?: string;
    fileName?: string;
} | {
    type: 'url';
    url: string;
    mimeType?: string;
    fileName?: string;
} | {
    type: 'inline';
    dataBase64: string;
    mimeType: string;
    fileName?: string;
} | {
    type: 'text';
    text: string;
    fileName?: string;
};

VideoSourceKind

Public type alias for Video Source Kind; the declaration contains its complete type expression.

• Kind: type
• Import: import type { VideoSourceKind } from '@codesoul-co/hypha-tools';
• Source module: media

Declaration

export type VideoSourceKind = 'video' | 'playlist' | 'collection' | 'live' | 'unknown';