@ai-matrx/api 0.0.0-stage → 0.1.1

package/dist/ai.d.cts

@@ -0,0 +1,493 @@
+import { A as Api, C as CallOptions, J as JsonOrStream, S as SseEvent } from './index-wC2vtb70.cjs';
+import { JsonValue } from './schemas.cjs';
+import './credentials.cjs';
+
+/**
+ * GENERATED by @ai-matrx/api scripts/generate.mjs from aidream/api-contract — never edit by hand.
+ * CONTRACT_SHA256 50a790edb39e682b46e0fa9e674faf5ce2a0ba7de2cd01930a497fca4c47844a
+ */
+
+/** AgentUsageReportResponse */
+type AgentUsageReportResponse = {
+    agents: AgentUsageRollupEntry[];
+    total_agents: number;
+    total_usages: number;
+};
+/** AgentUsageRollupEntry */
+type AgentUsageRollupEntry = {
+    agent_id: string;
+    agent_name?: string | null;
+    usage_count?: number;
+    breaking?: number;
+    silent_breaking?: number;
+    warning?: number;
+    info?: number;
+};
+/** AiCatalogReloadSummary */
+type AiCatalogReloadSummary = {
+    endpoints: number;
+    apis: number;
+    offerings: number;
+    settings: number;
+    providers: number;
+    models: number;
+    aliases: number;
+    quarantined: number;
+    refreshed_model_rows: number;
+    quarantined_rows: QuarantinedRowSummary[];
+};
+/** AiModelsResponse */
+type AiModelsResponse = {
+    models?: {
+        [key: string]: JsonValue;
+    }[];
+    count: number;
+};
+/** AnalyzeRequest */
+type AnalyzeRequest_MatrxLocal = {
+    url: string;
+    hardware?: HardwareInfo | null;
+};
+/** AvailabilityDriftSummary */
+type AvailabilityDriftSummary = {
+    mode: "off" | "report" | "park";
+    checked_providers: string[];
+    unservable?: UnservableOffering[];
+    parked?: string[];
+    restored?: string[];
+    held_back?: {
+        [key: string]: string;
+    };
+    write_failures?: string[];
+};
+/** One declared code usage — mirrors a row of public.agx_usage_registry. */
+type CodeAgentUsage = {
+    usage_key: string;
+    source_system: "matrx-ai" | "aidream";
+    ref_kind: "version" | "agent" | "builtin";
+    agent_version_id?: string | null;
+    agent_id?: string | null;
+    purpose: string;
+    code_path: string;
+};
+/** Stable public API name for the provider-owned embedding input contract. */
+type EmbeddingPart = {
+    type: "text" | "uri" | "inline";
+    text?: string | null;
+    uri?: string | null;
+    data?: string | null;
+    mime_type?: string | null;
+};
+/** EmbeddingRequest */
+type EmbeddingRequest = {
+    /** Organization context for the request; omitted to use the authenticated context. */
+    organization_id?: string | null;
+    /** Optional associated project selected by the caller. */
+    project_id?: string | null;
+    /** Optional associated task selected by the caller. */
+    task_id?: string | null;
+    /** Stable application slug that initiated the request. */
+    source_app?: string | null;
+    /** Stable feature slug within the source application. */
+    source_feature?: string | null;
+    /** How the client initiated this request: 'user' for a direct human action, 'auto' for client-code automation. Omit for API callers. */
+    initiation?: ("user" | "auto") | null;
+    model: string;
+    inputs: (string | EmbeddingPart[])[];
+    output_dimensionality?: number;
+    task_type?: string | null;
+    title?: string | null;
+};
+/** EmbeddingResponse */
+type EmbeddingResponse = {
+    model: string;
+    dimensions: number;
+    vectors: number[][];
+};
+/** HardwareInfo */
+type HardwareInfo = {
+    total_ram_mb: number;
+    gpu_vram_mb?: number | null;
+    supports_cuda?: boolean;
+    supports_metal?: boolean;
+    is_apple_silicon?: boolean;
+};
+/** HfAssistRequest */
+type HfAssistRequest = {
+    has_account?: boolean;
+};
+/** HfAssistResponse */
+type HfAssistResponse = {
+    status: "opened" | "token_ready" | "manual";
+    token?: string | null;
+    reason?: string | null;
+};
+/** ModelFileEntry */
+type ModelFileEntry = {
+    filename: string;
+    format: "gguf" | "safetensors" | "bin" | "onnx" | "other";
+    role: "main_model" | "mmproj" | "adapter" | "tokenizer" | "config" | "other";
+    quant: string | null;
+    is_split: boolean;
+    split_group: string | null;
+    part_index: number | null;
+    total_parts: number | null;
+    size_bytes: number;
+    total_size_bytes: number;
+    ram_required_gb: number;
+    compatibility_status: "works" | "needs_more_ram" | "accessory_only" | "incompatible_format";
+    compatibility_reason: string;
+    download_urls: string[];
+    recommended: boolean;
+};
+/** What the parameter-facts stage did. ``written`` is False on a dry run. */
+type ParameterFactsSummary = {
+    written: boolean;
+    sources: {
+        [key: string]: string;
+    };
+    providers: {
+        [key: string]: {
+            [key: string]: number;
+        };
+    };
+    write_failures?: string[];
+};
+/** Which providers to refresh. Omit ``provider_slugs`` for all supported. */
+type ProviderModelsRefreshRequest = {
+    /** ai.provider.slug values to refresh (openai, anthropic, groq, google, xai). Omit or null to refresh every supported provider. */
+    provider_slugs?: string[] | null;
+    /** Also rebuild provider_models_cache.parameter_facts (per-offering parameter truth from the provider snapshots, models.dev, OpenRouter and the Vercel AI Gateway). */
+    parameter_facts?: boolean;
+};
+/** ProviderModelsRefreshSummary */
+type ProviderModelsRefreshSummary = {
+    started_at: string;
+    refreshed: number;
+    missing_key: number;
+    no_provider_row: number;
+    failed: number;
+    results?: ProviderRefreshResult[];
+    parameter_facts?: ParameterFactsSummary | null;
+    availability?: AvailabilityDriftSummary | null;
+};
+/** What happened for ONE provider. Every status is reported, never dropped. */
+type ProviderRefreshResult = {
+    provider_slug: string;
+    provider_label: string;
+    provider_id?: string | null;
+    status: "refreshed" | "missing_key" | "no_provider_row" | "failed";
+    model_count?: number;
+    fetched_at?: string | null;
+    detail?: string | null;
+};
+/** QuarantinedRowSummary */
+type QuarantinedRowSummary = {
+    kind: string;
+    row_id: string;
+    name: string;
+    errors: string[];
+};
+/** RegistryDbRow */
+type RegistryDbRow = {
+    source_system: string;
+    usage_key: string;
+    ref_kind: string;
+    agent_id: string | null;
+    agent_version_id: string | null;
+    status: string;
+    purpose: string | null;
+    code_path: string | null;
+    last_synced_at: string | null;
+};
+/** RegistryDiffResponse */
+type RegistryDiffResponse = {
+    declared_count: number;
+    db_count: number;
+    declared: CodeAgentUsage[];
+    db_rows: RegistryDbRow[];
+    in_code_not_in_db: string[];
+    in_db_not_in_code: string[];
+    import_failures: string[];
+};
+/** RegistrySyncReport */
+type RegistrySyncReport = {
+    declared?: number;
+    created?: number;
+    updated?: number;
+    unchanged?: number;
+    vanished?: number;
+    broken_pins?: string[];
+    import_failures?: string[];
+    applied?: boolean;
+    skipped_reason?: string | null;
+};
+/** RepoAnalysisResult */
+type RepoAnalysisResult = {
+    provider: string;
+    repo_id: string;
+    repo_url: string;
+    author: string | null;
+    model_name: string | null;
+    architecture: string | null;
+    total_files: number;
+    hardware_label: string | null;
+    effective_capacity_gb: number | null;
+    files: ModelFileEntry[];
+};
+/** ScanSummary */
+type ScanSummary = {
+    success: boolean;
+    result_summary: string;
+    metadata: {
+        [key: string]: unknown;
+    };
+};
+/** SettingsProbeOutcome */
+type SettingsProbeOutcome = {
+    offering_id: string;
+    model_name: string;
+    api: string;
+    setting_key: string;
+    label: string;
+    value?: JsonValue;
+    wire?: {
+        [key: string]: JsonValue;
+    };
+    outcome: string;
+    detail?: string;
+    provider_message?: string | null;
+    provider_param?: string | null;
+    error_type?: string | null;
+    fingerprint?: string | null;
+    cost_usd?: number;
+    cell_id?: string | null;
+    evidence?: string;
+};
+/** One offering to probe now (settings-translation I2). */
+type SettingsProbeRequest = {
+    /** The ai.offering id to probe (one routable chat offering). */
+    offering_id: string;
+    /** Write each result as translation-cell evidence when the cell tables exist. */
+    write_evidence?: boolean;
+};
+/** SettingsProbeResponse */
+type SettingsProbeResponse = {
+    summary: string;
+    source: string;
+    started_at: string;
+    finished_at?: string | null;
+    catalog: string;
+    offerings_planned: number;
+    probes_planned: number;
+    probes_sent: number;
+    budget: {
+        [key: string]: number;
+    };
+    stopped_by_budget: boolean;
+    left_unprobed: number;
+    cost_usd: number;
+    evidence_mode: string;
+    evidence_reason: string;
+    outcomes: SettingsProbeOutcome[];
+    skipped_offerings: SettingsProbeSkippedOffering[];
+};
+/** SettingsProbeSkippedOffering */
+type SettingsProbeSkippedOffering = {
+    offering_id: string;
+    model_name: string;
+    api: string;
+    modality: string;
+    why: string;
+};
+/** An AVAILABLE offering the provider's own fresh list says it cannot serve. */
+type UnservableOffering = {
+    offering_id: string;
+    model_definition_id: string;
+    model_name: string;
+    provider_slug: string;
+    provider_model_id: string;
+    reason: "absent_from_provider_list" | "not_serverless";
+    retirement_candidate: boolean;
+};
+type GetAllAiModelsArgs = {
+    [key: string]: never;
+};
+type GetAllAiModelsResult = AiModelsResponse;
+/** Get All Ai Models */
+/** `GET /ai-models` · aidream · auth guest · org optional */
+declare function getAllAiModels(api: Api, args?: GetAllAiModelsArgs, options?: CallOptions): Promise<GetAllAiModelsResult>;
+type CreateEmbeddingsArgs = {
+    body: EmbeddingRequest;
+};
+type CreateEmbeddingsResult = EmbeddingResponse;
+/** Create Embeddings */
+/** `POST /ai/google/embeddings` · aidream · auth guest · org required */
+declare function createEmbeddings(api: Api, args: CreateEmbeddingsArgs, options?: CallOptions): Promise<CreateEmbeddingsResult>;
+type SyncRegisteredUsagesEndpointArgs = {
+    [key: string]: never;
+};
+type SyncRegisteredUsagesEndpointResult = RegistrySyncReport;
+/** Sync Registered Usages Endpoint */
+/** `POST /agent-usage/sync` · aidream · auth admin · org exempt */
+declare function syncRegisteredUsagesEndpoint(api: Api, args?: SyncRegisteredUsagesEndpointArgs, options?: CallOptions): Promise<SyncRegisteredUsagesEndpointResult>;
+type RegistryDiffEndpointArgs = {
+    [key: string]: never;
+};
+type RegistryDiffEndpointResult = RegistryDiffResponse;
+/** Registry Diff Endpoint */
+/** `GET /agent-usage/registry` · aidream · auth admin · org exempt */
+declare function registryDiffEndpoint(api: Api, args?: RegistryDiffEndpointArgs, options?: CallOptions): Promise<RegistryDiffEndpointResult>;
+type RunScanEndpointArgs = {
+    [key: string]: never;
+};
+type RunScanEndpointResult = ScanSummary;
+/** Run Scan Endpoint */
+/** `POST /agent-usage/scan` · aidream · auth admin · org exempt */
+declare function runScanEndpoint(api: Api, args?: RunScanEndpointArgs, options?: CallOptions): Promise<RunScanEndpointResult>;
+type ReportEndpointArgs = {
+    [key: string]: never;
+};
+type ReportEndpointResult = AgentUsageReportResponse;
+/** Report Endpoint */
+/** `GET /agent-usage/report` · aidream · auth admin · org exempt */
+declare function reportEndpoint(api: Api, args?: ReportEndpointArgs, options?: CallOptions): Promise<ReportEndpointResult>;
+type ReloadCatalogArgs = {
+    [key: string]: never;
+};
+type ReloadCatalogResult = AiCatalogReloadSummary;
+/** Reload Catalog */
+/** `POST /admin/ai-catalog/reload` · aidream · auth admin · org exempt */
+declare function reloadCatalog(api: Api, args?: ReloadCatalogArgs, options?: CallOptions): Promise<ReloadCatalogResult>;
+type RefreshProviderModelsArgs = {
+    body?: ProviderModelsRefreshRequest | null;
+};
+type RefreshProviderModelsResult = ProviderModelsRefreshSummary;
+/** Refresh Provider Models */
+/** `POST /admin/ai-catalog/provider-models/refresh` · aidream · auth admin · org exempt */
+declare function refreshProviderModels(api: Api, args?: RefreshProviderModelsArgs, options?: CallOptions): Promise<RefreshProviderModelsResult>;
+type RunSettingsProbeArgs = {
+    body: SettingsProbeRequest;
+};
+type RunSettingsProbeResult = SettingsProbeResponse;
+/** Run Settings Probe */
+/** `POST /admin/ai-catalog/settings-probe` · aidream · auth admin · org exempt */
+declare function runSettingsProbe(api: Api, args: RunSettingsProbeArgs, options?: CallOptions): Promise<RunSettingsProbeResult>;
+type AnalyzeRepoArgs = {
+    body: AnalyzeRequest_MatrxLocal;
+};
+type AnalyzeRepoResult = RepoAnalysisResult;
+/** Analyze Repo */
+/** `POST /model-repo/analyze` · matrx-local · auth loopback_token · org exempt */
+declare function analyzeRepo(api: Api, args: AnalyzeRepoArgs, options?: CallOptions): Promise<AnalyzeRepoResult>;
+type ListModelsArgs = {
+    [key: string]: never;
+};
+type ListModelsResult = {
+    [key: string]: unknown;
+};
+/** List Models */
+/** `GET /v1/models` · matrx-local · auth loopback_token · org exempt */
+declare function listModels(api: Api, args?: ListModelsArgs, options?: CallOptions): Promise<ListModelsResult>;
+type ChatCompletionsArgs = {
+    [key: string]: never;
+};
+type ChatCompletionsResult = unknown;
+/** Chat Completions */
+/** `POST /v1/chat/completions` · matrx-local · auth loopback_token · org exempt · sse_or_json */
+declare function chatCompletions(api: Api, args?: ChatCompletionsArgs, options?: CallOptions): Promise<JsonOrStream<ChatCompletionsResult, SseEvent>>;
+type AudioSpeechArgs = {
+    [key: string]: never;
+};
+type AudioSpeechResult = unknown;
+/** Audio Speech */
+/** `POST /v1/audio/speech` · matrx-local · auth loopback_token · org exempt */
+declare function audioSpeech(api: Api, args?: AudioSpeechArgs, options?: CallOptions): Promise<AudioSpeechResult>;
+type AudioTranscriptionsArgs = {
+    body: FormData;
+};
+type AudioTranscriptionsResult = unknown;
+/** Audio Transcriptions */
+/** `POST /v1/audio/transcriptions` · matrx-local · auth loopback_token · org exempt */
+declare function audioTranscriptions(api: Api, args: AudioTranscriptionsArgs, options?: CallOptions): Promise<AudioTranscriptionsResult>;
+type EmbeddingsArgs = {
+    [key: string]: never;
+};
+type EmbeddingsResult = unknown;
+/** Embeddings */
+/** `POST /v1/embeddings` · matrx-local · auth loopback_token · org exempt */
+declare function embeddings(api: Api, args?: EmbeddingsArgs, options?: CallOptions): Promise<EmbeddingsResult>;
+type HfTokenAssistArgs = {
+    body: HfAssistRequest;
+};
+type HfTokenAssistResult = HfAssistResponse;
+/** Hf Token Assist */
+/** `POST /hf-token/assist` · matrx-local · auth loopback_token · org exempt */
+declare function hfTokenAssist(api: Api, args: HfTokenAssistArgs, options?: CallOptions): Promise<HfTokenAssistResult>;
+/** Every JSON operation of this domain by `METHOD path` — for path-keyed calls. */
+interface Operations {
+    "GET /ai-models": {
+        args: GetAllAiModelsArgs;
+        result: GetAllAiModelsResult;
+    };
+    "POST /ai/google/embeddings": {
+        args: CreateEmbeddingsArgs;
+        result: CreateEmbeddingsResult;
+    };
+    "POST /agent-usage/sync": {
+        args: SyncRegisteredUsagesEndpointArgs;
+        result: SyncRegisteredUsagesEndpointResult;
+    };
+    "GET /agent-usage/registry": {
+        args: RegistryDiffEndpointArgs;
+        result: RegistryDiffEndpointResult;
+    };
+    "POST /agent-usage/scan": {
+        args: RunScanEndpointArgs;
+        result: RunScanEndpointResult;
+    };
+    "GET /agent-usage/report": {
+        args: ReportEndpointArgs;
+        result: ReportEndpointResult;
+    };
+    "POST /admin/ai-catalog/reload": {
+        args: ReloadCatalogArgs;
+        result: ReloadCatalogResult;
+    };
+    "POST /admin/ai-catalog/provider-models/refresh": {
+        args: RefreshProviderModelsArgs;
+        result: RefreshProviderModelsResult;
+    };
+    "POST /admin/ai-catalog/settings-probe": {
+        args: RunSettingsProbeArgs;
+        result: RunSettingsProbeResult;
+    };
+    "POST /model-repo/analyze": {
+        args: AnalyzeRepoArgs;
+        result: AnalyzeRepoResult;
+    };
+    "GET /v1/models": {
+        args: ListModelsArgs;
+        result: ListModelsResult;
+    };
+    "POST /v1/audio/speech": {
+        args: AudioSpeechArgs;
+        result: AudioSpeechResult;
+    };
+    "POST /v1/audio/transcriptions": {
+        args: AudioTranscriptionsArgs;
+        result: AudioTranscriptionsResult;
+    };
+    "POST /v1/embeddings": {
+        args: EmbeddingsArgs;
+        result: EmbeddingsResult;
+    };
+    "POST /hf-token/assist": {
+        args: HfTokenAssistArgs;
+        result: HfTokenAssistResult;
+    };
+}
+/** Path-keyed call, scoped to this domain only (never a global path map). */
+declare function call<K extends keyof Operations>(api: Api, key: K, args?: Operations[K]["args"], options?: CallOptions): Promise<Operations[K]["result"]>;
+
+export { type AgentUsageReportResponse, type AgentUsageRollupEntry, type AiCatalogReloadSummary, type AiModelsResponse, type AnalyzeRepoArgs, type AnalyzeRepoResult, type AnalyzeRequest_MatrxLocal, type AudioSpeechArgs, type AudioSpeechResult, type AudioTranscriptionsArgs, type AudioTranscriptionsResult, type AvailabilityDriftSummary, type ChatCompletionsArgs, type ChatCompletionsResult, type CodeAgentUsage, type CreateEmbeddingsArgs, type CreateEmbeddingsResult, type EmbeddingPart, type EmbeddingRequest, type EmbeddingResponse, type EmbeddingsArgs, type EmbeddingsResult, type GetAllAiModelsArgs, type GetAllAiModelsResult, type HardwareInfo, type HfAssistRequest, type HfAssistResponse, type HfTokenAssistArgs, type HfTokenAssistResult, type ListModelsArgs, type ListModelsResult, type ModelFileEntry, type Operations, type ParameterFactsSummary, type ProviderModelsRefreshRequest, type ProviderModelsRefreshSummary, type ProviderRefreshResult, type QuarantinedRowSummary, type RefreshProviderModelsArgs, type RefreshProviderModelsResult, type RegistryDbRow, type RegistryDiffEndpointArgs, type RegistryDiffEndpointResult, type RegistryDiffResponse, type RegistrySyncReport, type ReloadCatalogArgs, type ReloadCatalogResult, type RepoAnalysisResult, type ReportEndpointArgs, type ReportEndpointResult, type RunScanEndpointArgs, type RunScanEndpointResult, type RunSettingsProbeArgs, type RunSettingsProbeResult, type ScanSummary, type SettingsProbeOutcome, type SettingsProbeRequest, type SettingsProbeResponse, type SettingsProbeSkippedOffering, type SyncRegisteredUsagesEndpointArgs, type SyncRegisteredUsagesEndpointResult, type UnservableOffering, analyzeRepo, audioSpeech, audioTranscriptions, call, chatCompletions, createEmbeddings, embeddings, getAllAiModels, hfTokenAssist, listModels, refreshProviderModels, registryDiffEndpoint, reloadCatalog, reportEndpoint, runScanEndpoint, runSettingsProbe, syncRegisteredUsagesEndpoint };