@arke-institute/sdk 0.1.1 → 0.1.3

package/dist/query/index.d.ts

@@ -0,0 +1,636 @@
+/**
+ * Query package types for the Arke SDK
+ */
+/**
+ * Lineage filter to scope queries to a PI hierarchy
+ */
+interface LineageFilter {
+    /** The PI to start lineage resolution from */
+    sourcePi: string;
+    /** Direction to resolve the lineage */
+    direction: 'ancestors' | 'descendants' | 'both';
+}
+/**
+ * Options for path query execution
+ */
+interface PathQueryOptions {
+    /** Number of final results to return (default: 5) */
+    k?: number;
+    /** Beam width for exploration (default: k * 3) */
+    k_explore?: number;
+    /** Scope query to PI hierarchy */
+    lineage?: LineageFilter;
+    /** Fetch content for PI and File entities (default: false) */
+    enrich?: boolean;
+    /** Max characters per enriched entity (default: 2000) */
+    enrich_limit?: number;
+}
+/**
+ * Options for natural language query
+ */
+interface NaturalQueryOptions extends PathQueryOptions {
+    /** Additional instructions for the LLM translator */
+    custom_instructions?: string;
+}
+/**
+ * Enriched content from File or PI entities
+ */
+interface EnrichedContent {
+    text?: string;
+    data?: unknown;
+    format?: string;
+    truncated?: boolean;
+}
+/**
+ * Entity returned in query results
+ */
+interface Entity {
+    canonical_id: string;
+    code?: string;
+    label: string;
+    type: string;
+    properties: Record<string, unknown>;
+    created_by_pi?: string;
+    source_pis: string[];
+    content?: EnrichedContent;
+}
+/**
+ * A step in the traversal path
+ */
+interface PathStep {
+    /** Entity canonical_id (for entity steps) */
+    entity?: string;
+    /** Human-readable label */
+    label?: string;
+    /** Entity type */
+    type?: string;
+    /** Edge predicate (for edge steps) */
+    edge?: string;
+    /** Edge direction */
+    direction?: 'outgoing' | 'incoming';
+    /** Score for this step */
+    score?: number;
+}
+/**
+ * A single result with entity, path, and score
+ */
+interface QueryResultItem {
+    entity: Entity;
+    path: PathStep[];
+    score: number;
+}
+/**
+ * Metadata about lineage filtering
+ */
+interface LineageMetadata {
+    sourcePi: string;
+    direction: 'ancestors' | 'descendants' | 'both';
+    piCount: number;
+    truncated: boolean;
+}
+/**
+ * Metadata about query execution
+ */
+interface QueryMetadata {
+    /** The executed path query */
+    query: string;
+    /** Number of hops in the query */
+    hops: number;
+    /** Results requested */
+    k: number;
+    /** Beam width used */
+    k_explore: number;
+    /** Total candidates explored */
+    total_candidates_explored: number;
+    /** Execution time in milliseconds */
+    execution_time_ms: number;
+    /** Error code if query failed */
+    error?: string;
+    /** Error reason if query failed */
+    reason?: string;
+    /** Lineage filter metadata */
+    lineage?: LineageMetadata;
+    /** Partial path if traversal stopped early */
+    partial_path?: PathStep[];
+    /** Hop number where traversal stopped */
+    stopped_at_hop?: number;
+}
+/**
+ * Result from a path query
+ */
+interface QueryResult {
+    results: QueryResultItem[];
+    metadata: QueryMetadata;
+}
+/**
+ * Translation details from NL query
+ */
+interface TranslationInfo {
+    /** Generated path query */
+    path: string;
+    /** Explanation of what the query does */
+    explanation: string;
+    /** LLM tokens used */
+    tokens_used: number;
+    /** Estimated cost in USD */
+    cost_usd: number;
+    /** Number of translation attempts */
+    attempts?: number;
+    /** Validation errors encountered */
+    validation_errors?: Array<{
+        path: string;
+        error: string;
+        position?: number;
+    }>;
+}
+/**
+ * Result from a natural language query (includes translation info)
+ */
+interface NaturalQueryResult extends QueryResult {
+    translation: TranslationInfo;
+}
+/**
+ * Result from translate-only endpoint
+ */
+interface TranslateResult {
+    /** Generated path query */
+    path: string;
+    /** Explanation of what the query does */
+    explanation: string;
+    /** LLM tokens used */
+    tokens_used: number;
+    /** Estimated cost in USD */
+    cost_usd: number;
+}
+/**
+ * AST node types
+ */
+type ASTNodeType = 'semantic_search' | 'exact_entity' | 'type_filter' | 'combined_filter';
+/**
+ * Entry point AST node
+ */
+interface EntryAST {
+    type: ASTNodeType;
+    text?: string;
+    id?: string;
+    values?: string[];
+    semantic?: {
+        text: string;
+    };
+}
+/**
+ * Filter AST node
+ */
+interface FilterAST {
+    type: ASTNodeType;
+    text?: string;
+    id?: string;
+    values?: string[];
+    semantic?: {
+        text: string;
+    };
+}
+/**
+ * Hop AST node
+ */
+interface HopAST {
+    edge: {
+        direction: 'outgoing' | 'incoming' | 'bidirectional';
+        relation: {
+            type: 'wildcard';
+        } | {
+            type: 'terms';
+            terms: string[];
+        };
+        depth?: {
+            min: number;
+            max: number;
+        };
+    };
+    filter: FilterAST;
+}
+/**
+ * Parsed path query AST
+ */
+interface PathAST {
+    entry: EntryAST;
+    entry_filter?: FilterAST;
+    hops: HopAST[];
+}
+/**
+ * Result from parse endpoint
+ */
+interface ParseResult {
+    ast: PathAST;
+}
+/**
+ * Parse error response
+ */
+interface ParseError {
+    error: string;
+    message: string;
+    position?: number;
+}
+/**
+ * Entry point type documentation
+ */
+interface EntryPointDoc {
+    syntax: string;
+    name: string;
+    description: string;
+    example: string;
+    supportsHops: boolean;
+}
+/**
+ * Edge type documentation
+ */
+interface EdgeTypeDoc {
+    syntax: string;
+    description: string;
+}
+/**
+ * Variable depth syntax documentation
+ */
+interface VariableDepthDoc {
+    pattern: string;
+    description: string;
+}
+/**
+ * Filter type documentation
+ */
+interface FilterTypeDoc {
+    syntax: string;
+    description: string;
+    example?: string;
+}
+/**
+ * Parameter documentation
+ */
+interface ParameterDoc {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description: string;
+    enum?: string[];
+}
+/**
+ * Example query documentation
+ */
+interface ExampleDoc {
+    description: string;
+    query: string;
+}
+/**
+ * Full syntax documentation returned by /query/syntax
+ */
+interface SyntaxDocumentation {
+    version: string;
+    description: string;
+    entryPoints: {
+        description: string;
+        types: EntryPointDoc[];
+    };
+    edgeTraversal: {
+        description: string;
+        types: EdgeTypeDoc[];
+        variableDepth: {
+            description: string;
+            syntax: VariableDepthDoc[];
+        };
+    };
+    filters: {
+        description: string;
+        types: FilterTypeDoc[];
+    };
+    entityTypes: string[];
+    parameters: {
+        description: string;
+        fields: ParameterDoc[];
+        lineage: {
+            description: string;
+            fields: ParameterDoc[];
+        };
+    };
+    examples: ExampleDoc[];
+    constraints: string[];
+    errors: Record<string, string>;
+}
+/**
+ * Filter options for semantic search
+ */
+interface SemanticSearchFilter {
+    /** Filter by entity type(s) */
+    type?: string | string[];
+    /** Filter by source PI(s) - scopes search to entities from specific PIs */
+    source_pi?: string | string[];
+    /** Filter by merged entity source PIs - for searching across collections */
+    merged_entities_source_pis?: string | string[];
+}
+/**
+ * Options for direct semantic search
+ */
+interface SemanticSearchOptions {
+    /** Pinecone namespace to search (default: 'entities') */
+    namespace?: 'entities' | 'collections' | string;
+    /** Filter criteria */
+    filter?: SemanticSearchFilter;
+    /** Maximum number of results (default: 10, max: 100) */
+    top_k?: number;
+}
+/**
+ * Metadata returned with semantic search matches
+ */
+interface SemanticSearchMetadata {
+    /** Entity canonical ID */
+    canonical_id: string;
+    /** Entity label */
+    label: string;
+    /** Entity type */
+    type: string;
+    /** Entity code */
+    code?: string;
+    /** Source PI */
+    source_pi?: string;
+    /** Additional metadata fields */
+    [key: string]: unknown;
+}
+/**
+ * A single match from semantic search
+ */
+interface SemanticSearchMatch {
+    /** Vector ID (usually canonical_id) */
+    id: string;
+    /** Similarity score (0-1, higher is more similar) */
+    score: number;
+    /** Entity metadata */
+    metadata?: SemanticSearchMetadata;
+}
+/**
+ * Response from semantic search
+ */
+interface SemanticSearchResponse {
+    /** Matching entities ordered by similarity */
+    matches: SemanticSearchMatch[];
+}
+/**
+ * Options for collection search
+ */
+interface CollectionSearchOptions {
+    /** Maximum number of results (default: 10, max: 50) */
+    limit?: number;
+    /** Filter by visibility ('public' or 'private') */
+    visibility?: 'public' | 'private';
+}
+/**
+ * A collection result from search
+ */
+interface CollectionSearchResult {
+    /** Collection UUID */
+    id: string;
+    /** Semantic similarity score */
+    score: number;
+    /** Collection title */
+    title: string;
+    /** Collection slug */
+    slug: string;
+    /** Root PI of the collection */
+    rootPi: string;
+    /** Collection visibility */
+    visibility: 'public' | 'private';
+}
+/**
+ * Response from collection search
+ */
+interface CollectionSearchResponse {
+    /** Matching collections */
+    collections: CollectionSearchResult[];
+    /** Number of results returned */
+    count: number;
+}
+
+/**
+ * Configuration for QueryClient
+ */
+interface QueryClientConfig {
+    /**
+     * Gateway base URL (e.g., https://gateway.arke.institute).
+     * The client will call /query/* endpoints.
+     */
+    gatewayUrl: string;
+    /**
+     * Optional custom fetch implementation (useful for testing).
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Client for querying the Arke knowledge graph.
+ *
+ * All query endpoints are public and do not require authentication.
+ *
+ * @example
+ * ```typescript
+ * const query = new QueryClient({
+ *   gatewayUrl: 'https://gateway.arke.institute',
+ * });
+ *
+ * // Direct path query
+ * const results = await query.path('"alice austen" -[*]{,4}-> type:person');
+ *
+ * // Natural language query
+ * const nlResults = await query.natural('Find photographers connected to Alice Austen');
+ *
+ * // Get syntax documentation
+ * const syntax = await query.syntax();
+ * ```
+ */
+declare class QueryClient {
+    private baseUrl;
+    private fetchImpl;
+    constructor(config: QueryClientConfig);
+    private buildUrl;
+    private request;
+    /**
+     * Execute a path query against the knowledge graph.
+     *
+     * @param pathQuery - The path query string (e.g., '"alice austen" -[*]{,4}-> type:person')
+     * @param options - Query options (k, k_explore, lineage, enrich, etc.)
+     * @returns Query results with entities, paths, and metadata
+     *
+     * @example
+     * ```typescript
+     * // Simple semantic search
+     * const results = await query.path('"Washington" type:person');
+     *
+     * // Multi-hop traversal
+     * const results = await query.path('"alice austen" -[*]{,4}-> type:person ~ "photographer"');
+     *
+     * // With lineage filtering (collection scope)
+     * const results = await query.path('"letters" type:document', {
+     *   lineage: { sourcePi: 'arke:my_collection', direction: 'descendants' },
+     *   k: 10,
+     * });
+     * ```
+     */
+    path(pathQuery: string, options?: PathQueryOptions): Promise<QueryResult>;
+    /**
+     * Execute a natural language query.
+     *
+     * The query is translated to a path query using an LLM, then executed.
+     *
+     * @param question - Natural language question
+     * @param options - Query options including custom_instructions for the LLM
+     * @returns Query results with translation info
+     *
+     * @example
+     * ```typescript
+     * const results = await query.natural('Find photographers connected to Alice Austen');
+     * console.log('Generated query:', results.translation.path);
+     * console.log('Explanation:', results.translation.explanation);
+     * ```
+     */
+    natural(question: string, options?: NaturalQueryOptions): Promise<NaturalQueryResult>;
+    /**
+     * Translate a natural language question to a path query without executing it.
+     *
+     * Useful for understanding how questions are translated or for manual execution later.
+     *
+     * @param question - Natural language question
+     * @param customInstructions - Optional additional instructions for the LLM
+     * @returns Translation result with path query and explanation
+     *
+     * @example
+     * ```typescript
+     * const result = await query.translate('Who wrote letters from Philadelphia?');
+     * console.log('Path query:', result.path);
+     * // '"letters" <-[authored, wrote]- type:person -[located]-> "Philadelphia"'
+     * ```
+     */
+    translate(question: string, customInstructions?: string): Promise<TranslateResult>;
+    /**
+     * Parse and validate a path query without executing it.
+     *
+     * Returns the AST (Abstract Syntax Tree) if valid, or throws an error.
+     *
+     * @param pathQuery - The path query to parse
+     * @returns Parsed AST
+     * @throws QueryError if the query has syntax errors
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await query.parse('"test" -[*]-> type:person');
+     *   console.log('Valid query, AST:', result.ast);
+     * } catch (err) {
+     *   console.error('Invalid query:', err.message);
+     * }
+     * ```
+     */
+    parse(pathQuery: string): Promise<ParseResult>;
+    /**
+     * Get the path query syntax documentation.
+     *
+     * Returns comprehensive documentation including entry points, edge traversal,
+     * filters, examples, and constraints.
+     *
+     * @returns Syntax documentation
+     *
+     * @example
+     * ```typescript
+     * const syntax = await query.syntax();
+     *
+     * // List all entry point types
+     * syntax.entryPoints.types.forEach(ep => {
+     *   console.log(`${ep.syntax} - ${ep.description}`);
+     * });
+     *
+     * // Show examples
+     * syntax.examples.forEach(ex => {
+     *   console.log(`${ex.description}: ${ex.query}`);
+     * });
+     * ```
+     */
+    syntax(): Promise<SyntaxDocumentation>;
+    /**
+     * Check the health of the query service.
+     *
+     * @returns Health status
+     */
+    health(): Promise<{
+        status: string;
+        service: string;
+        version: string;
+    }>;
+    /**
+     * Direct semantic search against the vector index.
+     *
+     * This bypasses the path query syntax and directly queries Pinecone for
+     * semantically similar entities. Useful for:
+     * - Simple semantic searches without graph traversal
+     * - Scoped searches filtered by source_pi (collection scope)
+     * - Type-filtered semantic searches
+     *
+     * For graph traversal and path-based queries, use `path()` instead.
+     *
+     * @param text - Search query text
+     * @param options - Search options (namespace, filters, top_k)
+     * @returns Matching entities with similarity scores
+     *
+     * @example
+     * ```typescript
+     * // Simple semantic search
+     * const results = await query.semanticSearch('photographers from New York');
+     *
+     * // Scoped to a specific PI (collection)
+     * const scoped = await query.semanticSearch('portraits', {
+     *   filter: { source_pi: '01K75HQQXNTDG7BBP7PS9AWYAN' },
+     *   top_k: 20,
+     * });
+     *
+     * // Filter by type
+     * const people = await query.semanticSearch('artists', {
+     *   filter: { type: 'person' },
+     * });
+     *
+     * // Search across merged entities from multiple source PIs
+     * const merged = await query.semanticSearch('historical documents', {
+     *   filter: { merged_entities_source_pis: ['pi-1', 'pi-2'] },
+     * });
+     * ```
+     */
+    semanticSearch(text: string, options?: SemanticSearchOptions): Promise<SemanticSearchResponse>;
+    /**
+     * Search for collections by semantic similarity.
+     *
+     * Searches the dedicated collections index for fast semantic matching.
+     *
+     * @param query - Search query text
+     * @param options - Search options (limit, visibility filter)
+     * @returns Matching collections with similarity scores
+     *
+     * @example
+     * ```typescript
+     * // Search for photography-related collections
+     * const results = await query.searchCollections('photography');
+     * console.log(results.collections[0].title);
+     *
+     * // Search only public collections
+     * const publicResults = await query.searchCollections('history', {
+     *   visibility: 'public',
+     *   limit: 20,
+     * });
+     * ```
+     */
+    searchCollections(query: string, options?: CollectionSearchOptions): Promise<CollectionSearchResponse>;
+}
+
+/**
+ * Error class for query operations
+ */
+declare class QueryError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code?: string, details?: unknown | undefined);
+}
+
+export { type ASTNodeType, type CollectionSearchOptions, type CollectionSearchResponse, type CollectionSearchResult, type EdgeTypeDoc, type EnrichedContent, type Entity, type EntryAST, type EntryPointDoc, type ExampleDoc, type FilterAST, type FilterTypeDoc, type HopAST, type LineageFilter, type LineageMetadata, type NaturalQueryOptions, type NaturalQueryResult, type ParameterDoc, type ParseError, type ParseResult, type PathAST, type PathQueryOptions, type PathStep, QueryClient, type QueryClientConfig, QueryError, type QueryMetadata, type QueryResult, type QueryResultItem, type SemanticSearchFilter, type SemanticSearchMatch, type SemanticSearchMetadata, type SemanticSearchOptions, type SemanticSearchResponse, type SyntaxDocumentation, type TranslateResult, type TranslationInfo, type VariableDepthDoc };