@hasna/knowledge 0.2.27 → 0.2.28

package/dist/agent.d.ts

@@ -0,0 +1,35 @@
+import { type KnowledgeContextPack, type RetrievalOptions } from './retrieval';
+export interface KnowledgePromptOptions extends Omit<RetrievalOptions, 'query'> {
+    prompt: string;
+    generate?: boolean;
+    approveWrite?: boolean;
+    now?: Date;
+}
+export interface KnowledgePromptResult {
+    run_id: string;
+    prompt: string;
+    generated: boolean;
+    provider: string;
+    model: string;
+    answer: string;
+    context: KnowledgeContextPack;
+    citations: KnowledgeContextPack['citations'];
+    proposed_wiki_updates: Array<{
+        kind: 'answer_note';
+        title: string;
+        citations: string[];
+        requires_approval: boolean;
+    }>;
+    write_policy: {
+        approved: boolean;
+        durable_writes_performed: false;
+        reason: string;
+    };
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    };
+    warnings: string[];
+}
+export declare function runKnowledgePrompt(options: KnowledgePromptOptions): Promise<KnowledgePromptResult>;

package/dist/artifact-store.d.ts

@@ -0,0 +1,63 @@
+import type { KnowledgeConfig, KnowledgeWorkspace } from './workspace';
+interface S3ClientLike {
+    send(command: unknown): Promise<any>;
+}
+export interface ArtifactWrite {
+    key: string;
+    body: string | Uint8Array;
+    content_type?: string;
+    metadata?: Record<string, string>;
+}
+export interface ArtifactStore {
+    readonly type: 'local' | 's3';
+    readonly canRead: boolean;
+    readonly canWrite: boolean;
+    put(entry: ArtifactWrite): Promise<{
+        key: string;
+        uri: string;
+    }>;
+    getText(key: string): Promise<string>;
+    exists(key: string): Promise<boolean>;
+}
+export declare function normalizeArtifactKey(key: string): string;
+export declare class LocalArtifactStore implements ArtifactStore {
+    private readonly root;
+    readonly type: "local";
+    readonly canRead = true;
+    readonly canWrite = true;
+    constructor(root: string);
+    put(entry: ArtifactWrite): Promise<{
+        key: string;
+        uri: string;
+    }>;
+    getText(key: string): Promise<string>;
+    exists(key: string): Promise<boolean>;
+}
+export interface S3ArtifactStoreOptions {
+    bucket: string;
+    prefix?: string;
+    region?: string;
+    profile?: string;
+    max_attempts?: number;
+    server_side_encryption?: 'AES256' | 'aws:kms';
+    kms_key_id?: string;
+    client?: S3ClientLike;
+}
+export declare class S3ArtifactStore implements ArtifactStore {
+    private readonly options;
+    readonly type: "s3";
+    readonly canRead = true;
+    readonly canWrite = true;
+    private client?;
+    constructor(options: S3ArtifactStoreOptions);
+    private getClient;
+    private objectKey;
+    put(entry: ArtifactWrite): Promise<{
+        key: string;
+        uri: string;
+    }>;
+    getText(key: string): Promise<string>;
+    exists(key: string): Promise<boolean>;
+}
+export declare function createArtifactStore(config: KnowledgeConfig, workspace: KnowledgeWorkspace): ArtifactStore;
+export {};

package/dist/auth.d.ts

@@ -0,0 +1,35 @@
+import type { KnowledgeConfig } from './workspace';
+export interface KnowledgeAuthConfig {
+    api_key: string;
+    email?: string;
+    org_id?: string;
+    org_slug?: string;
+    user_id?: string;
+    api_url?: string;
+    created_at: string;
+}
+export interface KnowledgeAuthStatus {
+    authenticated: boolean;
+    source: 'env' | 'file' | 'none';
+    api_url: string;
+    auth_path: string;
+    email: string | null;
+    org_id: string | null;
+    org_slug: string | null;
+    user_id: string | null;
+    api_key_present: boolean;
+}
+export declare const DEFAULT_KNOWLEDGE_API_URL = "https://knowledge.hasna.xyz";
+export declare function normalizeKnowledgeApiOrigin(apiUrl: string): string;
+export declare function knowledgeAuthPath(env?: Record<string, string | undefined>): string;
+export declare function resolveKnowledgeApiUrl(config?: KnowledgeConfig, env?: Record<string, string | undefined>): string;
+export declare function getKnowledgeAuth(env?: Record<string, string | undefined>): KnowledgeAuthConfig | null;
+export declare function saveKnowledgeAuth(auth: Omit<KnowledgeAuthConfig, 'created_at'> & {
+    created_at?: string;
+}, env?: Record<string, string | undefined>): KnowledgeAuthConfig;
+export declare function clearKnowledgeAuth(env?: Record<string, string | undefined>): boolean;
+export declare function getKnowledgeApiKey(env?: Record<string, string | undefined>): {
+    apiKey: string | null;
+    source: KnowledgeAuthStatus['source'];
+};
+export declare function knowledgeAuthStatus(config?: KnowledgeConfig, env?: Record<string, string | undefined>): KnowledgeAuthStatus;

package/dist/embeddings.d.ts

@@ -0,0 +1,77 @@
+import { type AiProviderId } from './providers';
+import { type KnowledgeProvenance } from './provenance';
+import type { KnowledgeConfig } from './workspace';
+export interface EmbeddingRuntimeOptions {
+    config?: KnowledgeConfig;
+    env?: Record<string, string | undefined>;
+    modelRef?: string;
+    dimensions?: number;
+    fake?: boolean;
+    batchSize?: number;
+    maxParallelCalls?: number;
+}
+export interface EmbeddingIndexOptions extends EmbeddingRuntimeOptions {
+    dbPath: string;
+    limit?: number;
+    sourceRevisionId?: string;
+    now?: Date;
+}
+export interface EmbeddingSearchOptions extends EmbeddingRuntimeOptions {
+    dbPath: string;
+    query: string;
+    limit?: number;
+}
+export interface EmbeddingUsage {
+    input_tokens: number;
+}
+export interface EmbeddingVectorResult {
+    provider: AiProviderId;
+    model: string;
+    dimensions: number;
+    vectors: number[][];
+    usage: EmbeddingUsage;
+}
+export interface EmbeddingIndexResult {
+    provider: AiProviderId;
+    model: string;
+    dimensions: number;
+    chunks_seen: number;
+    chunks_embedded: number;
+    embeddings_upserted: number;
+    vector_entries_upserted: number;
+    usage: EmbeddingUsage;
+}
+export interface EmbeddingStatusResult {
+    total_embeddings: number;
+    total_vector_entries: number;
+    indexes: Array<{
+        provider: string;
+        model: string;
+        dimensions: number;
+        entries: number;
+        updated_at: string | null;
+    }>;
+}
+export interface SemanticSearchResult {
+    provider: AiProviderId;
+    model: string;
+    dimensions: number;
+    query: string;
+    results: Array<{
+        chunk_id: string;
+        score: number;
+        text: string;
+        source_uri: string | null;
+        source_ref: string | null;
+        revision: string | null;
+        hash: string | null;
+        provenance: KnowledgeProvenance | null;
+    }>;
+}
+export declare const DEFAULT_EMBEDDING_MODEL_REF = "openai:text-embedding-3-small";
+export declare const DEFAULT_EMBEDDING_DIMENSIONS = 1536;
+export declare function resolveEmbeddingModelRef(modelRef?: string, config?: KnowledgeConfig): string;
+export declare function embedTexts(texts: string[], options?: EmbeddingRuntimeOptions): Promise<EmbeddingVectorResult>;
+export declare function indexKnowledgeEmbeddings(options: EmbeddingIndexOptions): Promise<EmbeddingIndexResult>;
+export declare function embeddingIndexStatus(dbPath: string): EmbeddingStatusResult;
+export declare function searchVectorIndex(options: EmbeddingSearchOptions): Promise<SemanticSearchResult>;

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { createKnowledgeClient, createKnowledgeSdk, type KnowledgeAskOptions, type KnowledgeAuthInput, type KnowledgeClient, type KnowledgeClientOptions, type KnowledgeContextOptions, type KnowledgeSearchOptions, type KnowledgeSetupOptions, type KnowledgeWebSearchOptions, } from './sdk.js';
+export { createKnowledgeService, KnowledgeService, type KnowledgePathsResult, type KnowledgeServiceOptions, type KnowledgeSetupResult, } from './service.js';
+export { HASNA_KNOWLEDGE_APP_PATH, HASNA_XYZ_KNOWLEDGE_CANONICAL, canonicalHasnaXyzKnowledgeStorage, defaultKnowledgeConfig, ensureKnowledgeWorkspace, globalKnowledgeHome, projectKnowledgeHome, readKnowledgeConfig, resolveScopedWorkspace, workspaceForHome, writeKnowledgeConfig, type KnowledgeConfig, type KnowledgeWorkspace, } from './workspace.js';
+export { createArtifactStore, LocalArtifactStore, S3ArtifactStore, normalizeArtifactKey, type ArtifactStore, type ArtifactWrite, type S3ArtifactStoreOptions, } from './artifact-store.js';
+export { artifactKindForKey, hashArtifactBody, resolveStorageContract, validateStorageConfig, type GeneratedStorageObject, type StorageArtifactClass, type StorageContract, type StorageValidationResult, } from './storage-contract.js';
+export { parseSourceRef, catalogSourceUriForRef, revisionIdForSourceRef, isSupportedSourceRef, type BaseSourceRef, type FileSourceRef, type OpenFilesSourceRef, type S3SourceRef, type SourceRef, type SourceRefKind, type WebSourceRef, } from './source-ref.js';
+export { hybridSearch, type HybridSearchEntry, type HybridSearchOptions, type HybridSearchResult, type SearchProvenance, type SearchResultKind, } from './search.js';
+export { retrieveKnowledgeContext, type KnowledgeContextPack, type RetrievalCitation, type RetrievalExcerpt, type RetrievalGraphEvidence, type RetrievalOptions, type RerankedSearchEntry, } from './retrieval.js';
+export { runKnowledgePrompt, type KnowledgePromptOptions, type KnowledgePromptResult, } from './agent.js';
+export { DEFAULT_EMBEDDING_DIMENSIONS, DEFAULT_EMBEDDING_MODEL_REF, embedTexts, embeddingIndexStatus, indexKnowledgeEmbeddings, resolveEmbeddingModelRef, searchVectorIndex, type EmbeddingIndexOptions, type EmbeddingIndexResult, type EmbeddingRuntimeOptions, type EmbeddingSearchOptions, type EmbeddingStatusResult, type EmbeddingUsage, type EmbeddingVectorResult, type SemanticSearchResult, } from './embeddings.js';
+export { createAiSdkProviderRegistry, languageModelFor, listModelRegistry, modelAliases, parseModelRef, providerCredentialStatus, providerSettings, providerStatus, resolveModelRef, type AiProviderId, type AiProviderRuntimeOptions, type AiProviderSettings, type AiProvidersConfig, type ModelCapabilities, type ModelRegistryEntry, type ProviderCredentialStatus, type ProviderStatusResult, } from './providers.js';
+export { runProviderWebSearch, type WebSearchOptions, type WebSearchResult, type WebSearchSource, } from './web-search.js';
+export { compileWikiPage, fileAnswerToWiki, lintWiki, type WikiAnswerFileOptions, type WikiAnswerFileResult, type WikiCompileOptions, type WikiCompileResult, type WikiLintIssue, type WikiLintResult, } from './wiki-compiler.js';
+export { ingestOpenFilesManifest, ingestOpenFilesManifestItems, type ManifestIngestOptions, type ManifestIngestResult, type ManifestItemsIngestOptions, type ManifestObject, } from './manifest-ingest.js';
+export { ingestSourceRef, type SourceIngestOptions, type SourceIngestResult, } from './source-ingest.js';
+export { resolveOpenFilesSource, type ResolvedSourceChunk, type ResolvedSourceCitation, type SourceResolveOptions, type SourceResolveResult, type SourceResolverEvidence, } from './source-resolver.js';
+export { consumeOpenFilesOutbox, type OutboxConsumeOptions, type OutboxConsumeResult, } from './outbox-consume.js';
+export { enqueueMissingEmbeddings, refreshEmbeddingIndex, reindexHealth, type ReindexEmbeddingsResult, type ReindexEnqueueResult, type ReindexHealthResult, type ReindexRuntimeOptions, } from './reindex.js';
+export { DEFAULT_KNOWLEDGE_API_URL, clearKnowledgeAuth, getKnowledgeApiKey, getKnowledgeAuth, knowledgeAuthPath, knowledgeAuthStatus, normalizeKnowledgeApiOrigin, resolveKnowledgeApiUrl, saveKnowledgeAuth, type KnowledgeAuthConfig, type KnowledgeAuthStatus, } from './auth.js';
+export { REMOTE_KNOWLEDGE_CONTRACT_VERSION, RemoteKnowledgeClient, knowledgeRegistryContract, normalizeRemoteKnowledgeRunContract, type RemoteKnowledgeArtifact, type RemoteKnowledgeArtifactContract, type RemoteKnowledgeLogEntry, type RemoteKnowledgePromptRequest, type RemoteKnowledgeRegistryContract, type RemoteKnowledgeRunContract, type RemoteKnowledgeRunStatus, type RemoteKnowledgeSearchRequest, type RemoteKnowledgeSourceContract, type RemoteKnowledgeSyncRequest, } from './remote-client.js';