wauldo 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,590 @@
+/**
+ * Type definitions for Wauldo SDK
+ */
+interface ClientOptions {
+    /** Path to MCP server binary */
+    serverPath?: string;
+    /** Default timeout in milliseconds */
+    timeout?: number;
+    /** Automatically connect on first operation */
+    autoConnect?: boolean;
+}
+interface ReasoningOptions {
+    /** Depth of the thought tree (1-10) */
+    depth?: number;
+    /** Number of branches at each level (1-10) */
+    branches?: number;
+}
+interface ReasoningResult {
+    problem: string;
+    solution: string;
+    thoughtTree: string;
+    depth: number;
+    branches: number;
+    rawContent: string;
+}
+type SourceType = 'text' | 'code';
+interface Concept {
+    name: string;
+    conceptType: string;
+    weight: number;
+    description?: string;
+}
+interface ConceptResult {
+    concepts: Concept[];
+    sourceType: SourceType;
+    rawContent: string;
+}
+interface Chunk {
+    id: string;
+    content: string;
+    position: number;
+    priority: string;
+}
+interface ChunkResult {
+    chunks: Chunk[];
+    totalChunks: number;
+    rawContent: string;
+}
+interface RetrievalResult {
+    query: string;
+    results: Chunk[];
+    rawContent: string;
+}
+interface GraphNode {
+    id: string;
+    name: string;
+    nodeType: string;
+    weight: number;
+}
+interface KnowledgeGraphResult {
+    operation: string;
+    nodes: GraphNode[];
+    stats?: Record<string, unknown>;
+    rawContent: string;
+}
+type DetailLevel = 'brief' | 'normal' | 'detailed';
+interface PlanStep {
+    number: number;
+    title: string;
+    description: string;
+    priority: string;
+    effort: string;
+    dependencies: string[];
+}
+interface PlanResult {
+    task: string;
+    category: string;
+    steps: PlanStep[];
+    totalEffort: string;
+    rawContent: string;
+}
+interface PlanOptions {
+    /** Additional context or constraints */
+    context?: string;
+    /** Maximum number of steps (1-20) */
+    maxSteps?: number;
+    /** Level of detail for each step */
+    detailLevel?: DetailLevel;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+interface ToolContent {
+    type: 'text';
+    text: string;
+}
+interface CallToolResponse {
+    content: ToolContent[];
+    isError?: boolean;
+}
+
+/**
+ * Wauldo client implementation
+ */
+
+/**
+ * Client for Wauldo MCP Server
+ *
+ * @example
+ * ```typescript
+ * const client = new AgentClient();
+ * await client.connect();
+ *
+ * const result = await client.reason("How to optimize this algorithm?");
+ * console.log(result.solution);
+ *
+ * client.disconnect();
+ * ```
+ */
+declare class AgentClient {
+    private readonly transport;
+    private readonly autoConnect;
+    private connected;
+    constructor(options?: ClientOptions);
+    /**
+     * Connect to MCP server
+     */
+    connect(): Promise<this>;
+    /**
+     * Disconnect from MCP server
+     */
+    disconnect(): void;
+    /**
+     * Ensure client is connected
+     */
+    private ensureConnected;
+    /**
+     * List all available tools
+     */
+    listTools(): Promise<ToolDefinition[]>;
+    /**
+     * Call a tool by name
+     */
+    callTool(name: string, args: Record<string, unknown>): Promise<string>;
+    /**
+     * Perform Tree-of-Thought reasoning on a problem
+     *
+     * @example
+     * ```typescript
+     * const result = await client.reason(
+     *   "What's the best sorting algorithm for nearly sorted data?",
+     *   { depth: 4, branches: 3 }
+     * );
+     * console.log(result.solution);
+     * ```
+     */
+    reason(problem: string, options?: ReasoningOptions): Promise<ReasoningResult>;
+    private parseReasoningResult;
+    /**
+     * Extract concepts from text or code
+     *
+     * @example
+     * ```typescript
+     * const result = await client.extractConcepts(code, 'code');
+     * for (const concept of result.concepts) {
+     *   console.log(`${concept.name}: ${concept.weight}`);
+     * }
+     * ```
+     */
+    extractConcepts(text: string, sourceType?: SourceType): Promise<ConceptResult>;
+    private parseConceptResult;
+    /**
+     * Split a document into manageable chunks
+     */
+    chunkDocument(content: string, chunkSize?: number): Promise<ChunkResult>;
+    /**
+     * Retrieve relevant context for a query
+     */
+    retrieveContext(query: string, topK?: number): Promise<RetrievalResult>;
+    /**
+     * Summarize document content
+     */
+    summarize(content: string): Promise<string>;
+    /**
+     * Search the knowledge graph
+     */
+    searchKnowledge(query: string, limit?: number): Promise<KnowledgeGraphResult>;
+    /**
+     * Add concepts from text to knowledge graph
+     */
+    addToKnowledge(text: string): Promise<KnowledgeGraphResult>;
+    /**
+     * Get knowledge graph statistics
+     */
+    knowledgeStats(): Promise<KnowledgeGraphResult>;
+    /**
+     * Break down a task into actionable steps
+     *
+     * @example
+     * ```typescript
+     * const plan = await client.planTask(
+     *   "Implement user authentication",
+     *   { context: "Using JWT tokens", detailLevel: "detailed" }
+     * );
+     * for (const step of plan.steps) {
+     *   console.log(`${step.number}. ${step.title}`);
+     * }
+     * ```
+     */
+    planTask(task: string, options?: PlanOptions): Promise<PlanResult>;
+    private parsePlanResult;
+}
+
+/**
+ * HTTP API types for OpenAI-compatible endpoints
+ */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content?: string;
+    name?: string;
+}
+interface ChatRequest {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    stream?: boolean;
+    top_p?: number;
+    stop?: string[];
+}
+interface ChatUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: string | null;
+}
+interface ChatResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatChoice[];
+    usage: ChatUsage;
+}
+interface ModelInfo {
+    id: string;
+    object: string;
+    created: number;
+    owned_by: string;
+}
+interface ModelList {
+    object: string;
+    data: ModelInfo[];
+}
+interface EmbeddingData {
+    embedding: number[];
+    index: number;
+}
+interface EmbeddingUsage {
+    prompt_tokens: number;
+    total_tokens: number;
+}
+interface EmbeddingResponse {
+    data: EmbeddingData[];
+    model: string;
+    usage: EmbeddingUsage;
+}
+interface RagUploadResponse {
+    document_id: string;
+    chunks_count: number;
+}
+interface RagSource {
+    document_id: string;
+    content: string;
+    score: number;
+    chunk_id?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Audit trail for RAG responses — verification and accountability */
+interface RagAuditInfo {
+    confidence: number;
+    retrieval_path: string;
+    sources_evaluated: number;
+    sources_used: number;
+    best_score: number;
+    grounded: boolean;
+    confidence_label: string;
+    model: string;
+    latency_ms: number;
+    /** Retrieval funnel diagnostics (v1.6.5+) */
+    candidates_found?: number;
+    candidates_after_tenant?: number;
+    candidates_after_score?: number;
+    query_type?: string;
+}
+interface RagQueryResponse {
+    answer: string;
+    sources: RagSource[];
+    /** Full audit trail — always present on v1.6.5+ servers */
+    audit?: RagAuditInfo;
+    confidence?: number;
+    grounded?: boolean;
+}
+interface OrchestratorResponse {
+    final_output: string;
+}
+/** Minimal interface required by Conversation — implemented by both HttpClient and MockHttpClient */
+interface ChatClientLike {
+    chat(request: ChatRequest, options?: RequestOptions): Promise<ChatResponse>;
+}
+/** Log levels emitted by HttpClient */
+type LogLevel = 'debug' | 'warn' | 'error';
+interface HttpClientConfig {
+    baseUrl?: string;
+    apiKey?: string;
+    /** Extra headers added to every request (e.g. X-RapidAPI-Key) */
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    maxRetries?: number;
+    retryBackoffMs?: number;
+    /** Optional callback invoked on request lifecycle events */
+    onLog?: (level: LogLevel, message: string) => void;
+    /** Called before each HTTP request is sent */
+    onRequest?: (method: string, path: string) => void;
+    /** Called after each successful HTTP response */
+    onResponse?: (status: number, durationMs: number) => void;
+    /** Called when an HTTP request fails (after all retries exhausted) */
+    onError?: (error: Error) => void;
+}
+/** Options that can be passed per-request to override defaults */
+interface RequestOptions {
+    /** Override the default timeout for this specific request (milliseconds) */
+    timeoutMs?: number;
+}
+
+/**
+ * Conversation helper — manages chat history automatically.
+ */
+
+declare class Conversation {
+    private client;
+    private history;
+    private model;
+    constructor(client: ChatClientLike, options?: {
+        system?: string;
+        model?: string;
+    });
+    /**
+     * Send a user message and get the assistant reply.
+     * Both the user message and the assistant reply are appended to history.
+     *
+     * @param message - The user message to send
+     * @returns The assistant's reply content string
+     *
+     * @example
+     * ```typescript
+     * const conv = client.conversation({ system: 'You are helpful' });
+     * const reply = await conv.say('What is TypeScript?');
+     * const followUp = await conv.say('Show me an example'); // includes prior context
+     * ```
+     */
+    say(message: string): Promise<string>;
+    /**
+     * Return a copy of the full conversation history.
+     *
+     * @returns An array of ChatMessage objects (system, user, assistant turns)
+     *
+     * @example
+     * ```typescript
+     * const history = conv.getHistory();
+     * console.log(`${history.length} messages in conversation`);
+     * ```
+     */
+    getHistory(): ChatMessage[];
+    /**
+     * Clear user and assistant messages, preserving the system prompt (if any).
+     *
+     * @example
+     * ```typescript
+     * conv.clear();
+     * // System prompt is preserved; user/assistant messages are removed.
+     * ```
+     */
+    clear(): void;
+}
+
+/**
+ * HTTP client for Wauldo REST API (OpenAI-compatible)
+ *
+ * Uses Node 18+ built-in fetch — zero external dependencies.
+ */
+
+declare class HttpClient {
+    private retryConfig;
+    constructor(config?: HttpClientConfig);
+    /** GET /v1/models — List available LLM models */
+    listModels(): Promise<ModelList>;
+    /**
+     * POST /v1/chat/completions — Chat completion (non-streaming).
+     *
+     * @param request - The chat request (model, messages, temperature, etc.)
+     * @param options - Optional per-request overrides (e.g. timeoutMs)
+     * @returns The full chat completion response
+     *
+     * @example
+     * ```typescript
+     * const resp = await client.chat({
+     *   model: 'qwen2.5:7b',
+     *   messages: [{ role: 'user', content: 'Hello' }],
+     * });
+     * console.log(resp.choices[0]?.message?.content);
+     * ```
+     */
+    chat(request: ChatRequest, options?: RequestOptions): Promise<ChatResponse>;
+    /** Convenience: single message chat, returns content string */
+    chatSimple(model: string, message: string): Promise<string>;
+    /** POST /v1/chat/completions — SSE streaming, yields content chunks */
+    chatStream(request: ChatRequest, options?: RequestOptions): AsyncGenerator<string>;
+    /** POST /v1/embeddings — Generate text embeddings */
+    embeddings(input: string | string[], model: string): Promise<EmbeddingResponse>;
+    /**
+     * POST /v1/upload — Upload document for RAG indexing.
+     *
+     * @param content - The document text to index
+     * @param filename - Optional filename for the document
+     * @param options - Optional per-request overrides (e.g. timeoutMs)
+     * @returns Upload confirmation with document_id and chunks_count
+     */
+    ragUpload(content: string, filename?: string, options?: RequestOptions): Promise<RagUploadResponse>;
+    /** POST /v1/query — Query RAG knowledge base */
+    ragQuery(query: string, topK?: number, options?: {
+        debug?: boolean;
+        qualityMode?: string;
+    }): Promise<RagQueryResponse>;
+    /**
+     * Create a stateful conversation that tracks message history automatically.
+     *
+     * @param options - Optional system prompt and model name
+     * @returns A Conversation instance bound to this client
+     *
+     * @example
+     * ```typescript
+     * const conv = client.conversation({ system: 'You are a TypeScript expert' });
+     * const reply = await conv.say('What are generics?');
+     * ```
+     */
+    conversation(options?: {
+        system?: string;
+        model?: string;
+    }): Conversation;
+    /**
+     * Upload text to RAG, then query it — one-shot Q&A over a document.
+     *
+     * @param question - The question to ask about the document
+     * @param text - The document text to index and query
+     * @param source - Optional source name (defaults to 'document')
+     * @returns The answer string
+     */
+    ragAsk(question: string, text: string, source?: string): Promise<string>;
+    /** POST /v1/orchestrator/execute — Route to best specialist agent */
+    orchestrate(prompt: string): Promise<OrchestratorResponse>;
+    /** POST /v1/orchestrator/parallel — Run all 4 specialists in parallel */
+    orchestrateParallel(prompt: string): Promise<OrchestratorResponse>;
+}
+
+/**
+ * Mock HTTP client for testing without a running server
+ */
+
+/**
+ * Mock implementation of HttpClient for offline testing.
+ * Records all method calls in the `calls` array for assertions.
+ *
+ * @example
+ * ```typescript
+ * const mock = new MockHttpClient();
+ * const result = await mock.chat({ model: 'test', messages: [] });
+ * console.log(mock.calls); // [{ method: 'chat', args: [...] }]
+ * ```
+ */
+declare class MockHttpClient {
+    private chatResponse;
+    private modelList;
+    readonly calls: Array<{
+        method: string;
+        args: unknown[];
+    }>;
+    /**
+     * Configure the response returned by `chat()` and `chatSimple()`.
+     *
+     * @param response - The ChatResponse to return on subsequent chat calls
+     * @returns `this` for method chaining
+     *
+     * @example
+     * ```typescript
+     * const mock = new MockHttpClient().withChatResponse({
+     *   id: 'test-1', object: 'chat.completion', created: 0, model: 'test',
+     *   choices: [{ index: 0, message: { role: 'assistant', content: 'Hi' }, finish_reason: 'stop' }],
+     *   usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+     * });
+     * ```
+     */
+    withChatResponse(response: ChatResponse): this;
+    /**
+     * Configure the model list returned by `listModels()`.
+     *
+     * @param models - Array of ModelInfo objects
+     * @returns `this` for method chaining
+     *
+     * @example
+     * ```typescript
+     * const mock = new MockHttpClient().withModels([
+     *   { id: 'gpt-4', object: 'model', created: 0, owned_by: 'openai' },
+     * ]);
+     * ```
+     */
+    withModels(models: ModelInfo[]): this;
+    listModels(): Promise<ModelList>;
+    chat(request: ChatRequest, _options?: RequestOptions): Promise<ChatResponse>;
+    chatSimple(model: string, message: string): Promise<string>;
+    chatStream(_request: ChatRequest, _options?: RequestOptions): AsyncGenerator<string>;
+    embeddings(input: string | string[], model: string): Promise<EmbeddingResponse>;
+    ragUpload(content: string, filename?: string, _options?: RequestOptions): Promise<RagUploadResponse>;
+    ragQuery(query: string, topK?: number, options?: {
+        debug?: boolean;
+        qualityMode?: string;
+    }): Promise<RagQueryResponse>;
+    orchestrate(prompt: string): Promise<OrchestratorResponse>;
+    orchestrateParallel(prompt: string): Promise<OrchestratorResponse>;
+    conversation(options?: {
+        system?: string;
+        model?: string;
+    }): Conversation;
+    ragAsk(question: string, text: string, source?: string): Promise<string>;
+    private record;
+}
+
+/**
+ * Custom errors for Wauldo SDK
+ */
+/**
+ * Base error class for all Wauldo errors
+ */
+declare class WauldoError extends Error {
+    readonly code: number | undefined;
+    readonly data: unknown;
+    constructor(message: string, code?: number, data?: unknown);
+    toString(): string;
+}
+/**
+ * Thrown when connection to MCP server fails
+ */
+declare class ConnectionError extends WauldoError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when server returns an error response
+ */
+declare class ServerError extends WauldoError {
+    constructor(message: string, code?: number, data?: unknown);
+}
+/**
+ * Thrown when input validation fails
+ */
+declare class ValidationError extends WauldoError {
+    readonly field: string | undefined;
+    constructor(message: string, field?: string);
+}
+/**
+ * Thrown when operation times out
+ */
+declare class TimeoutError extends WauldoError {
+    readonly timeout: number | undefined;
+    constructor(message?: string, timeout?: number);
+}
+/**
+ * Thrown when requested tool is not available
+ */
+declare class ToolNotFoundError extends WauldoError {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
+
+export { AgentClient, type CallToolResponse, type ChatChoice, type ChatClientLike, type ChatMessage, type ChatRequest, type ChatResponse, type ChatUsage, type Chunk, type ChunkResult, type ClientOptions, type Concept, type ConceptResult, ConnectionError, Conversation, type DetailLevel, type EmbeddingData, type EmbeddingResponse, type EmbeddingUsage, type GraphNode, HttpClient, type HttpClientConfig, type KnowledgeGraphResult, type LogLevel, MockHttpClient, type ModelInfo, type ModelList, type OrchestratorResponse, type PlanOptions, type PlanResult, type PlanStep, type RagAuditInfo, type RagQueryResponse, type RagSource, type RagUploadResponse, type ReasoningOptions, type ReasoningResult, type RequestOptions, type RetrievalResult, ServerError, type SourceType, TimeoutError, type ToolContent, type ToolDefinition, ToolNotFoundError, ValidationError, WauldoError };