@codesoul-co/hypha-models / router

• Package index: @codesoul-co/hypha-models
• Source: packages/models/src/router.ts
• Exports: 10

Using this module

Use the Router module for using the public contracts and operations for this capability boundary. It exports 3 classes, 2 functions, 4 interfaces, 1 type.

Import from the package entrypoint

import {
  ModelAliasRegistry,
  ModelProviderError,
  ModelRouter,
  normalizeModelProviderError,
  parseModelTarget,
} from '@codesoul-co/hypha-models';

import type {
  ModelProviderErrorInit,
  ModelRouterOptions,
  NormalizedProviderErrorContext,
  ResolvedModelRoute,
  ModelProviderErrorCode,
} from '@codesoul-co/hypha-models';

Usage patterns

• Use the 5 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 3 classes as constructable runtime implementations. Each symbol entry lists its constructor and public methods.
• The module exposes 2 functions as direct operation entrypoints. Every overload, required/optional parameter, and return type is documented below.

Public exports

Symbol	Kind	Signature	Description
ModelAliasRegistry	class	new ModelAliasRegistry(aliases?: ModelAliasSpec[]): ModelAliasRegistry	Model Alias Registry class with 5 public constructor or member entries; its exact declarations are listed below.
ModelProviderError	class	new ModelProviderError(init: ModelProviderErrorInit): ModelProviderError	Model Provider Error class with 15 public constructor or member entries; its exact declarations are listed below.
ModelRouter	class	new ModelRouter(options: ModelRouterOptions): ModelRouter	Model Router class with 7 public constructor or member entries; its exact declarations are listed below.
normalizeModelProviderError	function	normalizeModelProviderError(error: unknown, context?: NormalizedProviderErrorContext): ModelProviderError	Normalize Model Provider Error function with 1 public call signature; parameters and return types are listed below.
parseModelTarget	function	parseModelTarget(target: string): Pick<ResolvedModelRoute, "providerId" | "providerModel"> | null	Parse Model Target function with 1 public call signature; parameters and return types are listed below.
ModelProviderErrorInit	interface	interface ModelProviderErrorInit	Model Provider Error Init interface with 8 public fields or methods.
ModelRouterOptions	interface	interface ModelRouterOptions	Model Router Options interface with 5 public fields or methods.
NormalizedProviderErrorContext	interface	interface NormalizedProviderErrorContext	Normalized Provider Error Context interface with 3 public fields or methods.
ResolvedModelRoute	interface	interface ResolvedModelRoute	Resolved Model Route interface with 4 public fields or methods.
ModelProviderErrorCode	type	type ModelProviderErrorCode = 'MODEL_PROVIDER_ERROR' | 'MODEL_PROVIDER_HTTP_ERROR' | 'MODEL_PROVIDER_TIMEOUT' | 'MODEL_PROVIDER_RATE_LIMITED' | 'MODEL_PROVIDER_AUTH_FAILED' | 'MODEL_PROVIDER_BAD_REQUEST' | 'MODEL_PROVIDER_STREAM_ERROR' | 'MODEL_PROVIDER_NOT_FOUND' | 'MODEL_ALIAS_NOT_FOUND' | 'MODEL_ROUTING_FAILED'	Public type alias for Model Provider Error Code; the declaration contains its complete type expression.

ModelAliasRegistry

Model Alias Registry class with 5 public constructor or member entries; its exact declarations are listed below.

• Kind: class
• Import: import { ModelAliasRegistry } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export declare class ModelAliasRegistry {
    constructor(aliases?: ModelAliasSpec[]);
    register(alias: ModelAliasSpec): void;
    registerTarget(alias: string, target: string, version?: string): ModelAliasSpec;
    resolve(aliasOrTarget: string): ResolvedModelRoute;
    list(): ModelAliasSpec[];
}

Public members

Member	Kind	Signature	Description
constructor	constructor	(aliases?: ModelAliasSpec[]): ModelAliasRegistry	Creates an instance of this class.
list	method	list(): ModelAliasSpec[]	Public method; parameters and return type are shown in the signature.
register	method	register(alias: ModelAliasSpec): void	Public method; parameters and return type are shown in the signature.
registerTarget	method	registerTarget(alias: string, target: string, version?: string): ModelAliasSpec	Public method; parameters and return type are shown in the signature.
resolve	method	resolve(aliasOrTarget: string): ResolvedModelRoute	Public method; parameters and return type are shown in the signature.

ModelProviderError

Model Provider Error class with 15 public constructor or member entries; its exact declarations are listed below.

• Kind: class
• Import: import { ModelProviderError } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export declare class ModelProviderError extends FrameworkError {
    readonly code: ModelProviderErrorCode;
    readonly providerId?: string;
    readonly modelAlias?: string;
    readonly status?: number;
    readonly retryable: boolean;
    readonly raw?: unknown;
    constructor(init: ModelProviderErrorInit);
}

Public members

Member	Kind	Signature	Description
cause	property	readonly cause?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
code	property	readonly code: ModelProviderErrorCode	Public property; its type, readonly modifier and optionality are shown in the signature.
constructor	constructor	(init: ModelProviderErrorInit): ModelProviderError	Creates an instance of this class.
context	property	readonly context?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
message	property	message: string	Public property; its type, readonly modifier and optionality are shown in the signature.
modelAlias	property	readonly modelAlias?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
name	property	name: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	readonly providerId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
raw	property	readonly raw?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
retryable	property	readonly retryable: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
stack	property	stack?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
static captureStackTrace	method	static captureStackTrace(targetObject: object, constructorOpt?: Function): void	Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called. js const myObject = {}; Error.captureStackTrace(myObject); myObject.stack; // Similar to `new Error().stack` The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}. The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace. The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance: js function a() { b(); } function b() { c(); } function c() { // Create an error without stack trace to avoid calculating the stack trace twice. const { stackTraceLimit } = Error; Error.stackTraceLimit = 0; const error = new Error(); Error.stackTraceLimit = stackTraceLimit; // Capture the stack trace above function b Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace throw error; } a();
static prepareStackTrace	method	static prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any	Public method; parameters and return type are shown in the signature.
static stackTraceLimit	property	static stackTraceLimit: number	The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.
status	property	readonly status?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

ModelRouter

Model Router class with 7 public constructor or member entries; its exact declarations are listed below.

• Kind: class
• Import: import { ModelRouter } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export declare class ModelRouter implements ModelProvider<ModelRequest, ModelResponse> {
    readonly id: string;
    constructor(options: ModelRouterOptions);
    capabilities(): ModelCapabilities;
    generate(request: ModelRequest): Promise<ModelResponse>;
    stream(request: ModelRequest): AsyncIterable<ModelStreamEvent>;
    resolve(aliasOrTarget: string): ResolvedModelRoute;
    listAliases(): ModelAliasSpec[];
}

Public members

Member	Kind	Signature	Description
capabilities	method	capabilities(): ModelCapabilities	Public method; parameters and return type are shown in the signature.
constructor	constructor	(options: ModelRouterOptions): ModelRouter	Creates an instance of this class.
generate	method	generate(request: ModelRequest): Promise<ModelResponse>	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.
listAliases	method	listAliases(): ModelAliasSpec[]	Public method; parameters and return type are shown in the signature.
resolve	method	resolve(aliasOrTarget: string): ResolvedModelRoute	Public method; parameters and return type are shown in the signature.
stream	method	stream(request: ModelRequest): AsyncIterable<ModelStreamEvent>	Public method; parameters and return type are shown in the signature.

normalizeModelProviderError

Normalize Model Provider Error function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { normalizeModelProviderError } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export declare function normalizeModelProviderError(error: unknown, context?: NormalizedProviderErrorContext): ModelProviderError;

Call signature

normalizeModelProviderError(error: unknown, context?: NormalizedProviderErrorContext): ModelProviderError

Parameters

Parameter	Type	Required	Description
error	unknown	Yes	Required parameter; accepted values are defined by the type column.
context	NormalizedProviderErrorContext	No	Optional parameter; accepted values are defined by the type column.

Returns

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

parseModelTarget

Parse Model Target function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { parseModelTarget } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export declare function parseModelTarget(target: string): Pick<ResolvedModelRoute, 'providerId' | 'providerModel'> | null;

Call signature

parseModelTarget(target: string): Pick<ResolvedModelRoute, "providerId" | "providerModel"> | null

Parameters

Parameter	Type	Required	Description
target	string	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: Pick<ResolvedModelRoute, "providerId" | "providerModel">
• Description: The return contract is defined by the type shown above.

ModelProviderErrorInit

Model Provider Error Init interface with 8 public fields or methods.

• Kind: interface
• Import: import type { ModelProviderErrorInit } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export interface ModelProviderErrorInit {
    code: ModelProviderErrorCode;
    message: string;
    providerId?: string;
    modelAlias?: string;
    status?: number;
    retryable?: boolean;
    raw?: unknown;
    cause?: unknown;
}

Contract members

Member	Kind	Signature	Description
cause	property	cause?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
code	property	code: ModelProviderErrorCode	Public property; its type, readonly modifier and optionality are shown in the signature.
message	property	message: string	Public property; its type, readonly modifier and optionality are shown in the signature.
modelAlias	property	modelAlias?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
raw	property	raw?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
retryable	property	retryable?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

ModelRouterOptions

Model Router Options interface with 5 public fields or methods.

• Kind: interface
• Import: import type { ModelRouterOptions } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export interface ModelRouterOptions {
    id?: string;
    registry: Pick<ModelRegistry, 'get' | 'list'>;
    aliases?: ModelAliasSpec[];
    routing?: ModelRoutingSpec;
    fallbackAliases?: string[];
}

Contract members

Member	Kind	Signature	Description
aliases	property	aliases?: ModelAliasSpec[]	Public property; its type, readonly modifier and optionality are shown in the signature.
fallbackAliases	property	fallbackAliases?: string[]	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.
registry	property	registry: Pick<ModelRegistry, "list" | "get">	Public property; its type, readonly modifier and optionality are shown in the signature.
routing	property	routing?: ModelRoutingSpec	Public property; its type, readonly modifier and optionality are shown in the signature.

NormalizedProviderErrorContext

Normalized Provider Error Context interface with 3 public fields or methods.

• Kind: interface
• Import: import type { NormalizedProviderErrorContext } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export interface NormalizedProviderErrorContext {
    providerId?: string;
    modelAlias?: string;
    operation?: 'generate' | 'stream' | 'count_tokens' | 'health';
}

Contract members

Member	Kind	Signature	Description
modelAlias	property	modelAlias?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operation	property	operation?: "generate" | "stream" | "count_tokens" | "health"	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ResolvedModelRoute

Resolved Model Route interface with 4 public fields or methods.

• Kind: interface
• Import: import type { ResolvedModelRoute } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export interface ResolvedModelRoute {
    alias: string;
    providerId: string;
    providerModel: string;
    spec?: ModelAliasSpec;
}

Contract members

Member	Kind	Signature	Description
alias	property	alias: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerModel	property	providerModel: string	Public property; its type, readonly modifier and optionality are shown in the signature.
spec	property	spec?: ModelAliasSpec	Public property; its type, readonly modifier and optionality are shown in the signature.

ModelProviderErrorCode

Public type alias for Model Provider Error Code; the declaration contains its complete type expression.

• Kind: type
• Import: import type { ModelProviderErrorCode } from '@codesoul-co/hypha-models';
• Source module: router

Declaration

export type ModelProviderErrorCode = 'MODEL_PROVIDER_ERROR' | 'MODEL_PROVIDER_HTTP_ERROR' | 'MODEL_PROVIDER_TIMEOUT' | 'MODEL_PROVIDER_RATE_LIMITED' | 'MODEL_PROVIDER_AUTH_FAILED' | 'MODEL_PROVIDER_BAD_REQUEST' | 'MODEL_PROVIDER_STREAM_ERROR' | 'MODEL_PROVIDER_NOT_FOUND' | 'MODEL_ALIAS_NOT_FOUND' | 'MODEL_ROUTING_FAILED';