@ragable/sdk 0.0.1 → 0.0.3

package/dist/index.d.mts

@@ -1,32 +1,230 @@
-interface AgentConfig {
+interface RagableClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+}
+type RequestOptions = Omit<RequestInit, "body"> & {
+    body?: unknown;
+};
+declare class RagableError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+declare function extractErrorMessage(payload: unknown, fallback: string): string;
+declare class RagableRequestClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    constructor(options: RagableClientOptions);
+    toUrl(path: string): string;
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Low-level fetch with API key and JSON body encoding. Caller handles status and body.
+     */
+    rawFetch(path: string, options?: RequestOptions): Promise<Response>;
+    private parseResponseBody;
+}
+
+interface ShiftIndex {
+    id: string;
     name: string;
-    model?: string;
-    memory?: boolean;
-    tools?: any[];
-    knowledge?: string[];
-}
-declare class Agent {
-    private config;
-    constructor(config: AgentConfig);
-    deploy(): Promise<{
-        status: string;
-        agentId: string;
-        url: string;
+    description: string | null;
+    dimensions: number;
+    embeddingModel: string;
+    status: string;
+    entryCount?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ShiftEntry {
+    id: string;
+    content: string;
+    metadata: unknown;
+    chunkIndex: number;
+    createdAt: string;
+}
+interface ShiftSearchResult {
+    content: string;
+    score: number;
+    metadata: unknown;
+}
+interface ShiftCreateIndexParams {
+    name: string;
+    description?: string;
+    dimensions?: number;
+    embeddingModel?: string;
+}
+interface ShiftUpdateIndexParams {
+    name?: string;
+    description?: string;
+}
+interface ShiftAddDocumentParams {
+    content: string;
+    metadata?: Record<string, unknown>;
+    chunkSize?: number;
+    chunkOverlap?: number;
+}
+type ShiftUploadableFile = Blob | ArrayBuffer | Uint8Array;
+interface ShiftUploadFileParams {
+    file: ShiftUploadableFile;
+    fileName?: string;
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+    chunkSize?: number;
+    chunkOverlap?: number;
+}
+interface ShiftListEntriesParams {
+    take?: number;
+    skip?: number;
+}
+interface ShiftSearchParams {
+    query: string;
+    topK?: number;
+}
+interface ShiftIngestResponse {
+    chunksCreated: number;
+    entries: string[];
+    extractedText?: string;
+    message?: string;
+}
+interface ShiftListEntriesResponse {
+    entries: ShiftEntry[];
+    total: number;
+}
+declare class ShiftClient {
+    private readonly client;
+    readonly indexes: {
+        list: () => Promise<{
+            indexes: ShiftIndex[];
+        }>;
+        create: (params: ShiftCreateIndexParams) => Promise<ShiftIndex>;
+        get: (indexId: string) => Promise<ShiftIndex>;
+        update: (indexId: string, params: ShiftUpdateIndexParams) => Promise<ShiftIndex>;
+        delete: (indexId: string) => Promise<{
+            success: true;
+        }>;
+    };
+    readonly documents: {
+        create: (indexId: string, params: ShiftAddDocumentParams) => Promise<ShiftIngestResponse>;
+        upload: (indexId: string, params: ShiftUploadFileParams) => Promise<ShiftIngestResponse>;
+    };
+    readonly entries: {
+        list: (indexId: string, params?: ShiftListEntriesParams) => Promise<ShiftListEntriesResponse>;
+        delete: (indexId: string, entryId: string) => Promise<{
+            success: true;
+        }>;
+    };
+    constructor(client: RagableRequestClient);
+    search(indexId: string, params: ShiftSearchParams): Promise<{
+        results: ShiftSearchResult[];
     }>;
-    run(input: string): Promise<{
-        response: string;
-        traceId: string;
+}
+
+interface AgentSummary {
+    id: string;
+    name: string;
+    description: string | null;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AgentChatMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+interface AgentChatParams {
+    message: string;
+    history?: AgentChatMessage[];
+}
+/** Mirrors backend ExecutionResult JSON shape (traces are opaque in the SDK). */
+interface AgentChatResult {
+    response: string;
+    traces: unknown[];
+    totalDurationMs: number;
+    httpResponse?: unknown;
+}
+/**
+ * Loose SSE event from POST /v1/agents/:id/chat/stream — narrows with `type` at runtime.
+ */
+type AgentStreamEvent = Record<string, unknown> & {
+    type: string;
+};
+declare class AgentsClient {
+    private readonly client;
+    constructor(client: RagableRequestClient);
+    list(): Promise<{
+        agents: AgentSummary[];
     }>;
+    get(agentId: string): Promise<AgentSummary>;
+    chat(agentId: string, params: AgentChatParams): Promise<AgentChatResult>;
+    /**
+     * Stream agent execution as SSE (`data: {json}` lines). Yields parsed JSON objects.
+     */
+    chatStream(agentId: string, params: AgentChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
 }
-declare class Tool {
-    static connect(apiKey: string): {
-        type: string;
-        connected: boolean;
+
+/** Minimal client surface for {@link createRagPipeline} (implemented by {@link Ragable}). */
+interface RagClientForPipeline {
+    shift: {
+        documents: {
+            create: (indexId: string, params: ShiftAddDocumentParams) => Promise<ShiftIngestResponse>;
+            upload: (indexId: string, params: ShiftUploadFileParams) => Promise<ShiftIngestResponse>;
+        };
+        search: (indexId: string, params: ShiftSearchParams) => Promise<{
+            results: ShiftSearchResult[];
+        }>;
     };
 }
-declare const _default: {
-    Agent: typeof Agent;
-    Tool: typeof Tool;
+interface FormatContextOptions {
+    /** Prepended before numbered passages (default: "Relevant passages:\\n") */
+    header?: string;
+    /** Joiner between passages (default: "\\n\\n") */
+    separator?: string;
+    /** Omit results with similarity score below this (default: no filter) */
+    minScore?: number;
+    /** Truncate total context string to this UTF-16 length (default: no limit) */
+    maxChars?: number;
+    /** Include similarity score in each block (default: false) */
+    includeScores?: boolean;
+}
+interface RagPipelineOptions {
+    indexId: string;
+}
+type RetrieveParams = ShiftSearchParams & {
+    format?: FormatContextOptions;
 };
+interface RagPipeline {
+    readonly indexId: string;
+    ingestText(params: ShiftAddDocumentParams): Promise<ShiftIngestResponse>;
+    ingestFile(params: ShiftUploadFileParams): Promise<ShiftIngestResponse>;
+    search(params: ShiftSearchParams): Promise<{
+        results: ShiftSearchResult[];
+    }>;
+    retrieve(params: RetrieveParams): Promise<{
+        results: ShiftSearchResult[];
+        context: string;
+    }>;
+}
+/**
+ * Turn vector search hits into a single block of text for system prompts or RAG user messages.
+ */
+declare function formatRetrievalContext(results: ShiftSearchResult[], options?: FormatContextOptions): string;
+/**
+ * High-level RAG helpers bound to one Shift index: ingest, search, retrieve with prompt-ready context.
+ */
+declare function createRagPipeline(client: RagClientForPipeline, options: RagPipelineOptions): RagPipeline;
+
+declare class Ragable {
+    readonly shift: ShiftClient;
+    readonly agents: AgentsClient;
+    readonly infrastructure: {
+        shift: ShiftClient;
+    };
+    constructor(options: RagableClientOptions);
+}
+declare function createClient(options: RagableClientOptions): Ragable;
 
-export { Agent, type AgentConfig, Tool, _default as default };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentStreamEvent, type AgentSummary, AgentsClient, type FormatContextOptions, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, type RagableClientOptions, RagableError, RagableRequestClient, type RequestOptions, type RetrieveParams, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, createClient, createRagPipeline, extractErrorMessage, formatRetrievalContext };

package/dist/index.d.ts

@@ -1,32 +1,230 @@
-interface AgentConfig {
+interface RagableClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+}
+type RequestOptions = Omit<RequestInit, "body"> & {
+    body?: unknown;
+};
+declare class RagableError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+declare function extractErrorMessage(payload: unknown, fallback: string): string;
+declare class RagableRequestClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    constructor(options: RagableClientOptions);
+    toUrl(path: string): string;
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Low-level fetch with API key and JSON body encoding. Caller handles status and body.
+     */
+    rawFetch(path: string, options?: RequestOptions): Promise<Response>;
+    private parseResponseBody;
+}
+
+interface ShiftIndex {
+    id: string;
     name: string;
-    model?: string;
-    memory?: boolean;
-    tools?: any[];
-    knowledge?: string[];
-}
-declare class Agent {
-    private config;
-    constructor(config: AgentConfig);
-    deploy(): Promise<{
-        status: string;
-        agentId: string;
-        url: string;
+    description: string | null;
+    dimensions: number;
+    embeddingModel: string;
+    status: string;
+    entryCount?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ShiftEntry {
+    id: string;
+    content: string;
+    metadata: unknown;
+    chunkIndex: number;
+    createdAt: string;
+}
+interface ShiftSearchResult {
+    content: string;
+    score: number;
+    metadata: unknown;
+}
+interface ShiftCreateIndexParams {
+    name: string;
+    description?: string;
+    dimensions?: number;
+    embeddingModel?: string;
+}
+interface ShiftUpdateIndexParams {
+    name?: string;
+    description?: string;
+}
+interface ShiftAddDocumentParams {
+    content: string;
+    metadata?: Record<string, unknown>;
+    chunkSize?: number;
+    chunkOverlap?: number;
+}
+type ShiftUploadableFile = Blob | ArrayBuffer | Uint8Array;
+interface ShiftUploadFileParams {
+    file: ShiftUploadableFile;
+    fileName?: string;
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+    chunkSize?: number;
+    chunkOverlap?: number;
+}
+interface ShiftListEntriesParams {
+    take?: number;
+    skip?: number;
+}
+interface ShiftSearchParams {
+    query: string;
+    topK?: number;
+}
+interface ShiftIngestResponse {
+    chunksCreated: number;
+    entries: string[];
+    extractedText?: string;
+    message?: string;
+}
+interface ShiftListEntriesResponse {
+    entries: ShiftEntry[];
+    total: number;
+}
+declare class ShiftClient {
+    private readonly client;
+    readonly indexes: {
+        list: () => Promise<{
+            indexes: ShiftIndex[];
+        }>;
+        create: (params: ShiftCreateIndexParams) => Promise<ShiftIndex>;
+        get: (indexId: string) => Promise<ShiftIndex>;
+        update: (indexId: string, params: ShiftUpdateIndexParams) => Promise<ShiftIndex>;
+        delete: (indexId: string) => Promise<{
+            success: true;
+        }>;
+    };
+    readonly documents: {
+        create: (indexId: string, params: ShiftAddDocumentParams) => Promise<ShiftIngestResponse>;
+        upload: (indexId: string, params: ShiftUploadFileParams) => Promise<ShiftIngestResponse>;
+    };
+    readonly entries: {
+        list: (indexId: string, params?: ShiftListEntriesParams) => Promise<ShiftListEntriesResponse>;
+        delete: (indexId: string, entryId: string) => Promise<{
+            success: true;
+        }>;
+    };
+    constructor(client: RagableRequestClient);
+    search(indexId: string, params: ShiftSearchParams): Promise<{
+        results: ShiftSearchResult[];
     }>;
-    run(input: string): Promise<{
-        response: string;
-        traceId: string;
+}
+
+interface AgentSummary {
+    id: string;
+    name: string;
+    description: string | null;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AgentChatMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+interface AgentChatParams {
+    message: string;
+    history?: AgentChatMessage[];
+}
+/** Mirrors backend ExecutionResult JSON shape (traces are opaque in the SDK). */
+interface AgentChatResult {
+    response: string;
+    traces: unknown[];
+    totalDurationMs: number;
+    httpResponse?: unknown;
+}
+/**
+ * Loose SSE event from POST /v1/agents/:id/chat/stream — narrows with `type` at runtime.
+ */
+type AgentStreamEvent = Record<string, unknown> & {
+    type: string;
+};
+declare class AgentsClient {
+    private readonly client;
+    constructor(client: RagableRequestClient);
+    list(): Promise<{
+        agents: AgentSummary[];
     }>;
+    get(agentId: string): Promise<AgentSummary>;
+    chat(agentId: string, params: AgentChatParams): Promise<AgentChatResult>;
+    /**
+     * Stream agent execution as SSE (`data: {json}` lines). Yields parsed JSON objects.
+     */
+    chatStream(agentId: string, params: AgentChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
 }
-declare class Tool {
-    static connect(apiKey: string): {
-        type: string;
-        connected: boolean;
+
+/** Minimal client surface for {@link createRagPipeline} (implemented by {@link Ragable}). */
+interface RagClientForPipeline {
+    shift: {
+        documents: {
+            create: (indexId: string, params: ShiftAddDocumentParams) => Promise<ShiftIngestResponse>;
+            upload: (indexId: string, params: ShiftUploadFileParams) => Promise<ShiftIngestResponse>;
+        };
+        search: (indexId: string, params: ShiftSearchParams) => Promise<{
+            results: ShiftSearchResult[];
+        }>;
     };
 }
-declare const _default: {
-    Agent: typeof Agent;
-    Tool: typeof Tool;
+interface FormatContextOptions {
+    /** Prepended before numbered passages (default: "Relevant passages:\\n") */
+    header?: string;
+    /** Joiner between passages (default: "\\n\\n") */
+    separator?: string;
+    /** Omit results with similarity score below this (default: no filter) */
+    minScore?: number;
+    /** Truncate total context string to this UTF-16 length (default: no limit) */
+    maxChars?: number;
+    /** Include similarity score in each block (default: false) */
+    includeScores?: boolean;
+}
+interface RagPipelineOptions {
+    indexId: string;
+}
+type RetrieveParams = ShiftSearchParams & {
+    format?: FormatContextOptions;
 };
+interface RagPipeline {
+    readonly indexId: string;
+    ingestText(params: ShiftAddDocumentParams): Promise<ShiftIngestResponse>;
+    ingestFile(params: ShiftUploadFileParams): Promise<ShiftIngestResponse>;
+    search(params: ShiftSearchParams): Promise<{
+        results: ShiftSearchResult[];
+    }>;
+    retrieve(params: RetrieveParams): Promise<{
+        results: ShiftSearchResult[];
+        context: string;
+    }>;
+}
+/**
+ * Turn vector search hits into a single block of text for system prompts or RAG user messages.
+ */
+declare function formatRetrievalContext(results: ShiftSearchResult[], options?: FormatContextOptions): string;
+/**
+ * High-level RAG helpers bound to one Shift index: ingest, search, retrieve with prompt-ready context.
+ */
+declare function createRagPipeline(client: RagClientForPipeline, options: RagPipelineOptions): RagPipeline;
+
+declare class Ragable {
+    readonly shift: ShiftClient;
+    readonly agents: AgentsClient;
+    readonly infrastructure: {
+        shift: ShiftClient;
+    };
+    constructor(options: RagableClientOptions);
+}
+declare function createClient(options: RagableClientOptions): Ragable;
 
-export { Agent, type AgentConfig, Tool, _default as default };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentStreamEvent, type AgentSummary, AgentsClient, type FormatContextOptions, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, type RagableClientOptions, RagableError, RagableRequestClient, type RequestOptions, type RetrieveParams, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, createClient, createRagPipeline, extractErrorMessage, formatRetrievalContext };