@hasna/knowledge 0.2.27 → 0.2.29

package/dist/service.d.ts

@@ -0,0 +1,117 @@
+import { type KnowledgeAuthStatus } from './auth';
+import { type KnowledgePromptOptions } from './agent';
+import { type EmbeddingIndexOptions, type EmbeddingSearchOptions } from './embeddings';
+import { type ProviderStatusResult, type ModelRegistryEntry } from './providers';
+import { type ReindexRuntimeOptions } from './reindex';
+import { RemoteKnowledgeClient, type RemoteKnowledgeRegistryContract } from './remote-client';
+import { type RetrievalOptions } from './retrieval';
+import { type HybridSearchOptions } from './search';
+import { type WebSearchOptions } from './web-search';
+import { type WikiCompileOptions } from './wiki-compiler';
+import { type StorageContract, type StorageValidationResult } from './storage-contract';
+import { type KnowledgeConfig, type KnowledgeWorkspace } from './workspace';
+export interface KnowledgeServiceOptions {
+    scope?: string;
+    cwd?: string;
+}
+export interface KnowledgePathsResult {
+    ok: true;
+    scope: string;
+    home: string;
+    config_path: string;
+    json_store_path: string;
+    knowledge_db_path: string;
+    artifacts_dir: string;
+    indexes_dir: string;
+    logs_dir: string;
+    runs_dir: string;
+    schemas_dir: string;
+    wiki_dir: string;
+    config: KnowledgeConfig;
+    message: string;
+}
+export interface KnowledgeSetupResult {
+    ok: true;
+    mode: KnowledgeConfig['mode'];
+    api_url: string | null;
+    storage_type: KnowledgeConfig['storage']['type'];
+    artifact_uri_prefix: string;
+    canonical_hasna_xyz: StorageContract['canonical_hasna_xyz'];
+    config_path: string;
+    next: string[];
+    message: string;
+}
+export declare class KnowledgeService {
+    private readonly options;
+    private ensuredWorkspace?;
+    private cachedConfig?;
+    constructor(options?: KnowledgeServiceOptions);
+    get scope(): string;
+    get workspace(): KnowledgeWorkspace;
+    ensureWorkspace(): KnowledgeWorkspace;
+    jsonStorePath(): string;
+    config(): KnowledgeConfig;
+    safetyPolicy(): import("./safety").SafetyPolicy;
+    artifactStore(): import("./artifact-store").ArtifactStore;
+    storageContract(): StorageContract;
+    validateStorage(): StorageValidationResult;
+    setup(options?: {
+        mode?: string;
+        apiUrl?: string;
+        canonicalHasnaXyz?: boolean;
+    }): KnowledgeSetupResult;
+    authStatus(env?: Record<string, string | undefined>): KnowledgeAuthStatus;
+    saveAuth(input: {
+        apiKey: string;
+        email?: string;
+        orgId?: string;
+        orgSlug?: string;
+        userId?: string;
+        apiUrl?: string;
+    }, env?: Record<string, string | undefined>): import("./auth").KnowledgeAuthConfig;
+    clearAuth(env?: Record<string, string | undefined>): boolean;
+    remoteContract(): RemoteKnowledgeRegistryContract;
+    remoteClient(env?: Record<string, string | undefined>): RemoteKnowledgeClient | null;
+    paths(): KnowledgePathsResult;
+    initDb(): {
+        path: string;
+        schema_version: number;
+    };
+    dbStats(): import("./knowledge-db").KnowledgeDbStats;
+    initWiki(): Promise<import("./wiki-layout").WikiLayoutInitResult>;
+    compileWiki(options?: Omit<WikiCompileOptions, 'dbPath' | 'store'>): Promise<import("./wiki-compiler").WikiCompileResult>;
+    fileAnswer(options: {
+        prompt: string;
+        answer: string;
+        approveWrite?: boolean;
+        limit?: number;
+        semantic?: boolean;
+        modelRef?: string;
+        dimensions?: number;
+        fake?: boolean;
+    }): Promise<import("./wiki-compiler").WikiAnswerFileResult>;
+    lintWiki(): import("./wiki-compiler").WikiLintResult;
+    ingestManifest(input: string): Promise<import("./manifest-ingest").ManifestIngestResult>;
+    ingestSource(sourceRef: string, purpose?: string): Promise<import("./source-ingest").SourceIngestResult>;
+    resolveSource(sourceRef: string, options?: {
+        purpose?: string;
+        limit?: number;
+    }): Promise<import("./source-resolver").SourceResolveResult>;
+    consumeOutbox(input: string): Promise<import("./outbox-consume").OutboxConsumeResult>;
+    reindexHealth(options?: Omit<ReindexRuntimeOptions, 'dbPath' | 'config'>): import("./reindex").ReindexHealthResult;
+    enqueueReindex(options?: Omit<ReindexRuntimeOptions, 'dbPath' | 'config'>): import("./reindex").ReindexEnqueueResult;
+    refreshEmbeddings(options?: Omit<ReindexRuntimeOptions & {
+        full?: boolean;
+        limit?: number;
+    }, 'dbPath' | 'config'>): Promise<import("./reindex").ReindexEmbeddingsResult>;
+    providerStatus(env?: Record<string, string | undefined>): ProviderStatusResult;
+    modelRegistry(): ModelRegistryEntry[];
+    embeddingStatus(): import("./embeddings").EmbeddingStatusResult;
+    indexEmbeddings(options?: Omit<EmbeddingIndexOptions, 'dbPath' | 'config'>): Promise<import("./embeddings").EmbeddingIndexResult>;
+    semanticSearch(options: Omit<EmbeddingSearchOptions, 'dbPath' | 'config'>): Promise<import("./embeddings").SemanticSearchResult>;
+    search(options: Omit<HybridSearchOptions, 'dbPath' | 'config'>): Promise<import("./search").HybridSearchResult>;
+    retrieveContext(options: Omit<RetrievalOptions, 'dbPath' | 'config'>): Promise<import("./retrieval").KnowledgeContextPack>;
+    runPrompt(options: Omit<KnowledgePromptOptions, 'dbPath' | 'config'>): Promise<import("./agent").KnowledgePromptResult>;
+    webSearch(options: Omit<WebSearchOptions, 'dbPath' | 'config' | 'safetyPolicy'>): Promise<import("./web-search").WebSearchResult>;
+}
+export declare function createKnowledgeService(options?: KnowledgeServiceOptions): KnowledgeService;

package/dist/source-ingest.d.ts

@@ -0,0 +1,18 @@
+import { type ManifestIngestResult } from './manifest-ingest';
+import type { KnowledgeConfig } from './workspace';
+import { type SafetyPolicy } from './safety';
+export interface SourceIngestOptions {
+    dbPath: string;
+    sourceRef: string;
+    purpose?: string;
+    config?: KnowledgeConfig;
+    safetyPolicy?: SafetyPolicy;
+    now?: Date;
+}
+export interface SourceIngestResult extends ManifestIngestResult {
+    source_ref: string;
+    content_source: 'catalog_chunks' | 'extracted_text_ref' | 'file' | 's3' | 'web';
+    read_only: true;
+    hash: string;
+}
+export declare function ingestSourceRef(options: SourceIngestOptions): Promise<SourceIngestResult>;

package/dist/source-ref.d.ts

@@ -0,0 +1,30 @@
+export type SourceRefKind = 'open-files' | 's3' | 'file' | 'web';
+export interface BaseSourceRef {
+    kind: SourceRefKind;
+    uri: string;
+}
+export interface OpenFilesSourceRef extends BaseSourceRef {
+    kind: 'open-files';
+    entity: 'file' | 'source';
+    id: string;
+    revision_id?: string;
+    path?: string;
+}
+export interface S3SourceRef extends BaseSourceRef {
+    kind: 's3';
+    bucket: string;
+    key: string;
+}
+export interface FileSourceRef extends BaseSourceRef {
+    kind: 'file';
+    path: string;
+}
+export interface WebSourceRef extends BaseSourceRef {
+    kind: 'web';
+    url: string;
+}
+export type SourceRef = OpenFilesSourceRef | S3SourceRef | FileSourceRef | WebSourceRef;
+export declare function parseSourceRef(uri: string): SourceRef;
+export declare function catalogSourceUriForRef(uri: string, parsed?: SourceRef): string;
+export declare function revisionIdForSourceRef(uri: string): string | null;
+export declare function isSupportedSourceRef(uri: string): boolean;

package/dist/source-resolver.d.ts

@@ -0,0 +1,92 @@
+import { type KnowledgeProvenance } from './provenance';
+import { type SafetyPolicy } from './safety';
+export interface SourceResolveOptions {
+    dbPath: string;
+    sourceRef: string;
+    purpose?: string;
+    limit?: number;
+    now?: Date;
+    safetyPolicy?: SafetyPolicy;
+}
+export interface SourceResolverEvidence {
+    resolver: 'open-files-read-only';
+    mode: 'local_catalog';
+    purpose: string;
+    read_only: true;
+    source_ref: string;
+    source_uri: string;
+    source_revision_id: string | null;
+    revision: string | null;
+    hash: string | null;
+    chunk_id?: string;
+    start_offset?: number | null;
+    end_offset?: number | null;
+    resolved_at: string;
+}
+export interface ResolvedSourceChunk {
+    id: string;
+    kind: string;
+    ordinal: number;
+    text: string;
+    token_count: number | null;
+    start_offset: number | null;
+    end_offset: number | null;
+    metadata: Record<string, unknown>;
+    evidence: SourceResolverEvidence;
+    provenance: KnowledgeProvenance;
+}
+export interface ResolvedSourceCitation {
+    source_ref: string;
+    source_uri: string;
+    chunk_id: string;
+    quote: string;
+    start_offset: number | null;
+    end_offset: number | null;
+    evidence: SourceResolverEvidence;
+    provenance: KnowledgeProvenance;
+}
+export interface SourceResolveResult {
+    source_ref: string;
+    source_uri: string;
+    purpose: string;
+    read_only: true;
+    resolved: boolean;
+    resolver: {
+        name: 'open-files-read-only';
+        mode: 'local_catalog';
+        contract: 'open-files-knowledge-source-v1';
+    };
+    source: {
+        id: string;
+        uri: string;
+        kind: string;
+        title: string | null;
+        metadata: Record<string, unknown>;
+        permissions: Record<string, unknown>;
+        updated_at: string;
+    } | null;
+    revision: {
+        id: string;
+        revision: string;
+        hash: string | null;
+        extracted_text_uri: string | null;
+        metadata: Record<string, unknown>;
+        created_at: string;
+        reindex_required: boolean;
+    } | null;
+    content: {
+        mime: string | null;
+        size: number | null;
+        hash: string | null;
+        text_available: boolean;
+        chunks_total: number;
+        chunks_returned: number;
+        char_count_returned: number;
+        extracted_text_ref: string | null;
+        bytes_available: false;
+        bytes_exposed: false;
+    };
+    chunks: ResolvedSourceChunk[];
+    citations: ResolvedSourceCitation[];
+}
+export declare function resolveOpenFilesSource(options: SourceResolveOptions): Promise<SourceResolveResult>;

package/dist/storage-contract.d.ts

@@ -0,0 +1,106 @@
+import type { Database } from 'bun:sqlite';
+import { REMOTE_KNOWLEDGE_CONTRACT_VERSION } from './remote-client';
+import type { KnowledgeConfig, KnowledgeWorkspace } from './workspace';
+import { HASNA_XYZ_KNOWLEDGE_CANONICAL } from './workspace';
+export interface StorageArtifactClass {
+    kind: string;
+    prefix: string;
+    description: string;
+}
+export interface StorageContract {
+    scope: string;
+    mode: KnowledgeConfig['mode'];
+    storage_type: KnowledgeConfig['storage']['type'];
+    workspace_home: string;
+    local_layout: {
+        app_path: string;
+        config_path: string;
+        json_store_path: string;
+        knowledge_db_path: string;
+        directories: Record<string, string>;
+    };
+    artifact_store: {
+        type: KnowledgeConfig['storage']['type'];
+        artifacts_root: string;
+        uri_prefix: string;
+        s3: {
+            bucket: string;
+            prefix: string;
+            region: string | null;
+            profile: string | null;
+            server_side_encryption: string | null;
+            kms_key_configured: boolean;
+        } | null;
+    };
+    canonical_hasna_xyz: {
+        division: typeof HASNA_XYZ_KNOWLEDGE_CANONICAL.division;
+        app_type: typeof HASNA_XYZ_KNOWLEDGE_CANONICAL.app_type;
+        app: typeof HASNA_XYZ_KNOWLEDGE_CANONICAL.app;
+        env: typeof HASNA_XYZ_KNOWLEDGE_CANONICAL.env;
+        active: boolean;
+        local_path: string;
+        s3: {
+            bucket: string;
+            region: string;
+            profile: string;
+            prefix: string;
+            uri_prefix: string;
+            server_side_encryption: string;
+        };
+        secrets: {
+            env: string;
+            aws: string;
+            s3: string;
+            rds: null;
+            future_rds: string;
+        };
+        evidence_doc: string;
+    };
+    hosted: {
+        enabled: boolean;
+        api_url: string;
+        api_url_env: 'KNOWLEDGE_API_URL';
+        api_key_env: 'KNOWLEDGE_API_KEY';
+        auth_storage: '~/.hasna/knowledge/auth.json';
+        remote_contract_version: typeof REMOTE_KNOWLEDGE_CONTRACT_VERSION;
+        requires_hosted_account_for_local_use: false;
+    };
+    source_ownership: {
+        owner: 'open-files';
+        preferred_ref: string;
+        allowed_schemes: string[];
+        raw_source_bytes_stored_in_open_knowledge: false;
+        stores: string[];
+        does_not_store: string[];
+    };
+    generated_artifacts: StorageArtifactClass[];
+    scalability: {
+        catalog: string;
+        indexes: string;
+        logs: string;
+        markdown: string;
+    };
+    warnings: string[];
+}
+export interface StorageValidationResult {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface GeneratedStorageObject {
+    uri: string;
+    key: string;
+    kind: string;
+    content_type?: string;
+    hash?: string;
+    size_bytes?: number;
+    metadata?: Record<string, unknown>;
+}
+export declare function hashArtifactBody(body: string | Uint8Array): {
+    hash: string;
+    size_bytes: number;
+};
+export declare function artifactKindForKey(key: string): string;
+export declare function resolveStorageContract(config: KnowledgeConfig, workspace: KnowledgeWorkspace, scope?: string): StorageContract;
+export declare function validateStorageConfig(config: KnowledgeConfig, workspace: KnowledgeWorkspace): StorageValidationResult;
+export declare function recordStorageObjects(db: Database, objects: GeneratedStorageObject[], now?: Date): void;

package/dist/web-search.d.ts

@@ -0,0 +1,40 @@
+import { type AiProviderId } from './providers';
+import { type SafetyPolicy } from './safety';
+import type { KnowledgeConfig } from './workspace';
+export interface WebSearchOptions {
+    dbPath: string;
+    query: string;
+    config?: KnowledgeConfig;
+    safetyPolicy?: SafetyPolicy;
+    modelRef?: string;
+    provider?: AiProviderId;
+    limit?: number;
+    maxUses?: number;
+    domains?: string[];
+    fake?: boolean;
+    fileResults?: boolean;
+    env?: Record<string, string | undefined>;
+    now?: Date;
+}
+export interface WebSearchSource {
+    url: string;
+    title: string | null;
+    snippet: string | null;
+    provider_metadata: Record<string, unknown>;
+}
+export interface WebSearchResult {
+    run_id: string;
+    query: string;
+    provider: string;
+    model: string;
+    answer: string;
+    sources: WebSearchSource[];
+    filed_sources: number;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    };
+    warnings: string[];
+}
+export declare function runProviderWebSearch(options: WebSearchOptions): Promise<WebSearchResult>;

package/dist/wiki-compiler.d.ts

@@ -0,0 +1,67 @@
+import type { ArtifactStore } from './artifact-store';
+import type { KnowledgeContextPack } from './retrieval';
+export interface WikiCompileOptions {
+    dbPath: string;
+    store: ArtifactStore;
+    title?: string;
+    query?: string;
+    sourceRefs?: string[];
+    limit?: number;
+    now?: Date;
+}
+export interface WikiCompileResult {
+    page_id: string;
+    path: string;
+    artifact_uri: string;
+    content_hash: string;
+    chunks_seen: number;
+    citations_written: number;
+    concept_page_id: string | null;
+    indexes_updated: number;
+    log_key: string;
+    warnings: string[];
+}
+export interface WikiAnswerFileOptions {
+    dbPath: string;
+    store: ArtifactStore;
+    prompt: string;
+    answer: string;
+    context: KnowledgeContextPack;
+    approveWrite?: boolean;
+    now?: Date;
+}
+export interface WikiAnswerFileResult {
+    approved: boolean;
+    durable_writes_performed: boolean;
+    page_id: string | null;
+    path: string | null;
+    artifact_uri: string | null;
+    citations_written: number;
+    log_key: string | null;
+    message: string;
+}
+export interface WikiLintIssue {
+    type: 'missing_citation' | 'stale_citation' | 'duplicate_page' | 'orphan_page' | 'unresolved_source_ref' | 'contradiction_marker' | 'new_article_candidate';
+    severity: 'info' | 'warn' | 'error';
+    page_id?: string;
+    path?: string;
+    source_uri?: string;
+    chunk_id?: string;
+    message: string;
+}
+export interface WikiLintResult {
+    ok: boolean;
+    issue_count: number;
+    issues: WikiLintIssue[];
+    counts: {
+        active_pages: number;
+        citations: number;
+        backlinks: number;
+        new_article_candidates: number;
+    };
+}
+export declare function compileWikiPage(options: WikiCompileOptions): Promise<WikiCompileResult>;
+export declare function fileAnswerToWiki(options: WikiAnswerFileOptions): Promise<WikiAnswerFileResult>;
+export declare function lintWiki(options: {
+    dbPath: string;
+}): WikiLintResult;

package/dist/wiki-layout.d.ts

@@ -0,0 +1,23 @@
+import type { Database } from 'bun:sqlite';
+import type { ArtifactStore } from './artifact-store';
+import { type GeneratedStorageObject } from './storage-contract';
+export interface WikiLayoutInitResult {
+    schema_key: string;
+    root_index_key: string;
+    wiki_readme_key: string;
+    log_key: string;
+    artifacts: GeneratedStorageObject[];
+    written: string[];
+}
+interface CatalogArtifact {
+    key: string;
+    uri: string;
+    hash?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare function agentSchemaTemplate(): string;
+export declare function rootIndexTemplate(): string;
+export declare function wikiReadmeTemplate(): string;
+export declare function initializeWikiLayout(store: ArtifactStore, now?: Date): Promise<WikiLayoutInitResult>;
+export declare function recordWikiLayoutCatalog(db: Database, artifacts: CatalogArtifact[], now?: Date): void;
+export {};

package/dist/workspace.d.ts

@@ -0,0 +1,111 @@
+export declare const HASNA_KNOWLEDGE_APP_PATH: string;
+export interface KnowledgeWorkspace {
+    home: string;
+    configPath: string;
+    jsonStorePath: string;
+    knowledgeDbPath: string;
+    artifactsDir: string;
+    cacheDir: string;
+    exportsDir: string;
+    indexesDir: string;
+    logsDir: string;
+    runsDir: string;
+    schemasDir: string;
+    wikiDir: string;
+}
+export interface KnowledgeConfig {
+    version: 1;
+    mode: 'local' | 'hosted';
+    hosted?: {
+        api_url?: string;
+    };
+    storage: {
+        type: 'local' | 's3';
+        artifacts_root: string;
+        s3?: {
+            bucket: string;
+            prefix?: string;
+            region?: string;
+            profile?: string;
+            max_attempts?: number;
+            server_side_encryption?: 'AES256' | 'aws:kms';
+            kms_key_id?: string;
+        };
+    };
+    sources: {
+        preferred_ref: 'open-files';
+        allowed_schemes: string[];
+    };
+    embeddings?: {
+        default_model?: string;
+        dimensions?: number;
+        batch_size?: number;
+        max_parallel_calls?: number;
+    };
+    providers?: {
+        default_model?: string;
+        aliases?: Record<string, string>;
+        openai?: {
+            api_key_env?: string;
+            base_url?: string;
+            default_model?: string;
+        };
+        anthropic?: {
+            api_key_env?: string;
+            base_url?: string;
+            default_model?: string;
+        };
+        deepseek?: {
+            api_key_env?: string;
+            base_url?: string;
+            default_model?: string;
+        };
+    };
+    safety?: {
+        network?: {
+            web_search_enabled?: boolean;
+            s3_reads_enabled?: boolean;
+            allowed_s3_buckets?: string[];
+        };
+        redaction?: {
+            enabled?: boolean;
+        };
+        approvals?: {
+            generated_writes_require_approval?: boolean;
+        };
+    };
+}
+export declare const HASNA_XYZ_KNOWLEDGE_CANONICAL: {
+    readonly division: "xyz";
+    readonly app_type: "opensource";
+    readonly app: "knowledge";
+    readonly env: "prod";
+    readonly local_path: string;
+    readonly s3: {
+        readonly bucket: "hasna-xyz-opensource-knowledge-prod";
+        readonly region: "us-east-1";
+        readonly profile: "hasna-xyz-infra";
+        readonly prefix: ".hasna/apps/knowledge";
+        readonly server_side_encryption: "AES256";
+    };
+    readonly secrets: {
+        readonly env: "hasna/xyz/opensource/knowledge/prod/env";
+        readonly aws: "hasna/xyz/opensource/knowledge/prod/aws";
+        readonly s3: "hasna/xyz/opensource/knowledge/prod/s3";
+        readonly rds: any;
+        readonly future_rds: "hasna/xyz/opensource/knowledge/prod/rds";
+    };
+    readonly source_owner: "open-files";
+    readonly evidence_doc: "docs/canonical-secrets-bootstrap-2026-06-08.md";
+};
+export declare function canonicalHasnaXyzKnowledgeStorage(): KnowledgeConfig['storage'];
+export declare function legacyGlobalStorePath(): string;
+export declare function globalKnowledgeHome(): string;
+export declare function projectKnowledgeHome(cwd?: string): string;
+export declare function workspaceForHome(home: string): KnowledgeWorkspace;
+export declare function defaultKnowledgeConfig(): KnowledgeConfig;
+export declare function ensureKnowledgeWorkspace(home: string): KnowledgeWorkspace;
+export declare function resolveScopedWorkspace(scope: string | undefined, cwd?: string): KnowledgeWorkspace;
+export declare function ensureParentDir(path: string): void;
+export declare function readKnowledgeConfig(path: string): KnowledgeConfig;
+export declare function writeKnowledgeConfig(path: string, config: KnowledgeConfig): void;