rust-kgdb 0.5.12 → 0.5.13

package/index.d.ts

@@ -989,3 +989,738 @@ export class AgentBuilder {
    */
   build(): ComposedAgent
 }
+
+// ==============================================
+// Memory Layer (v0.5.13+) - GraphDB-Powered Agent Memory
+// ==============================================
+
+/**
+ * AgentState - Lifecycle states for agent runtime
+ */
+export const AgentState: {
+  CREATED: 'CREATED'
+  READY: 'READY'
+  RUNNING: 'RUNNING'
+  PAUSED: 'PAUSED'
+  COMPLETED: 'COMPLETED'
+  FAILED: 'FAILED'
+}
+
+export type AgentStateType = 'CREATED' | 'READY' | 'RUNNING' | 'PAUSED' | 'COMPLETED' | 'FAILED'
+
+/**
+ * Memory retrieval weight configuration
+ */
+export interface RetrievalWeights {
+  /** Weight for recency (time decay), typically 0.3 */
+  recency: number
+  /** Weight for relevance (semantic similarity), typically 0.5 */
+  relevance: number
+  /** Weight for importance (access frequency), typically 0.2 */
+  importance: number
+}
+
+/**
+ * AgentRuntime configuration
+ */
+export interface AgentRuntimeConfig {
+  /** Custom agent ID (auto-generated if not provided) */
+  id?: string
+  /** Agent name */
+  name?: string
+  /** Agent version */
+  version?: string
+  /** Working memory capacity (default: 100 items) */
+  workingMemoryCapacity?: number
+  /** Episodic memory retention in days (default: 30) */
+  episodicRetentionDays?: number
+  /** Memory retrieval weights */
+  retrievalWeights?: RetrievalWeights
+  /** Recency decay rate per hour (default: 0.995) */
+  recencyDecayRate?: number
+}
+
+/**
+ * AgentRuntime - Core agent identity and state management
+ *
+ * Provides:
+ * - Unique agent identity (UUID)
+ * - Lifecycle state management
+ * - Memory layer orchestration
+ * - Execution context tracking
+ *
+ * @example
+ * ```typescript
+ * const runtime = new AgentRuntime({
+ *   name: 'fraud-detector',
+ *   version: '1.0.0',
+ *   workingMemoryCapacity: 200
+ * })
+ *
+ * runtime.ready()
+ * const execId = runtime.startExecution('Find fraud patterns')
+ * // ... do work ...
+ * const execution = runtime.completeExecution({ findings: [...] }, true)
+ * ```
+ */
+export class AgentRuntime {
+  /** Agent unique identifier */
+  readonly id: string
+  /** Agent name */
+  readonly name: string
+  /** Agent version */
+  readonly version: string
+  /** Creation timestamp */
+  readonly createdAt: string
+  /** Current state */
+  state: AgentStateType
+  /** State transition history */
+  stateHistory: Array<{ state: AgentStateType; timestamp: string; reason: string }>
+  /** Memory configuration */
+  memoryConfig: {
+    workingMemoryCapacity: number
+    episodicRetentionDays: number
+    retrievalWeights: RetrievalWeights
+    recencyDecayRate: number
+  }
+  /** Execution metrics */
+  metrics: {
+    totalExecutions: number
+    successfulExecutions: number
+    failedExecutions: number
+    totalMemoryRetrievals: number
+    avgExecutionTimeMs: number
+  }
+
+  constructor(config?: AgentRuntimeConfig)
+
+  /** Transition to a new state */
+  transitionTo(newState: AgentStateType, reason?: string): this
+
+  /** Mark agent as ready */
+  ready(): this
+
+  /** Start a new execution */
+  startExecution(prompt: string): string
+
+  /** Complete current execution */
+  completeExecution(result: unknown, success?: boolean): {
+    id: string
+    prompt: string
+    startTime: number
+    endTime: number
+    durationMs: number
+    result: unknown
+    success: boolean
+  } | undefined
+
+  /** Get agent identity information */
+  getIdentity(): {
+    id: string
+    name: string
+    version: string
+    createdAt: string
+    state: AgentStateType
+    executionCount: number
+    lastActiveAt: string
+  }
+
+  /** Get runtime metrics */
+  getMetrics(): {
+    totalExecutions: number
+    successfulExecutions: number
+    failedExecutions: number
+    totalMemoryRetrievals: number
+    avgExecutionTimeMs: number
+    uptime: number
+    currentState: AgentStateType
+  }
+}
+
+/**
+ * WorkingMemory - Current execution context (in-memory)
+ *
+ * Fast, ephemeral memory for the current task:
+ * - Current conversation context
+ * - Active bindings and variables
+ * - Tool execution results (recent)
+ * - Scratchpad for reasoning
+ *
+ * @example
+ * ```typescript
+ * const memory = new WorkingMemory(100)
+ *
+ * memory.addContext({ type: 'user_input', content: 'Find claims' })
+ * memory.setBinding('claim_id', 'CLM-2024-001')
+ * memory.storeToolResult('kg.sparql.query', {}, { count: 5 })
+ * memory.setFocus('http://example.org/claim/123')
+ *
+ * const recent = memory.getRecentContext(5)
+ * memory.clear()
+ * ```
+ */
+export class WorkingMemory {
+  /** Maximum context items */
+  capacity: number
+  /** Current context items */
+  context: Array<{ id: string; timestamp: number; [key: string]: unknown }>
+  /** Variable bindings */
+  bindings: Map<string, { value: unknown; timestamp: number; accessCount: number }>
+  /** Scratchpad for reasoning */
+  scratchpad: Map<string, unknown>
+  /** Recent tool results */
+  toolResults: Array<{ tool: string; args: unknown; result: unknown; timestamp: number }>
+  /** Current focus entity */
+  focus: { entity: string; timestamp: number } | null
+
+  constructor(capacity?: number)
+
+  /** Add context item */
+  addContext(item: Record<string, unknown>): this
+
+  /** Set variable binding */
+  setBinding(key: string, value: unknown): this
+
+  /** Get variable binding (returns null if not found) */
+  getBinding(key: string): unknown | null
+
+  /** Store tool execution result */
+  storeToolResult(toolName: string, args: unknown, result: unknown): this
+
+  /** Set current focus entity */
+  setFocus(entity: string): this
+
+  /** Write to scratchpad */
+  scratch(key: string, value: unknown): this
+
+  /** Read from scratchpad */
+  readScratch(key: string): unknown | undefined
+
+  /** Get recent context items */
+  getRecentContext(limit?: number): Array<Record<string, unknown>>
+
+  /** Clear all working memory */
+  clear(): this
+
+  /** Export memory state */
+  export(): {
+    context: Array<Record<string, unknown>>
+    bindings: Record<string, unknown>
+    scratchpad: Record<string, unknown>
+    toolResults: Array<Record<string, unknown>>
+    focus: { entity: string; timestamp: number } | null
+  }
+}
+
+/**
+ * EpisodicMemory - Execution history stored in GraphDB
+ *
+ * Persistent memory of agent executions:
+ * - Past prompts and responses
+ * - Tool invocation history
+ * - Success/failure outcomes
+ * - Temporal relationships
+ *
+ * @example
+ * ```typescript
+ * const db = new GraphDB('http://example.org/agent')
+ * const episodic = new EpisodicMemory(db, 'http://hypermind.ai/episodic/')
+ *
+ * await episodic.storeEpisode('agent_123', {
+ *   id: 'exec_456',
+ *   prompt: 'Find fraud',
+ *   durationMs: 150,
+ *   success: true
+ * })
+ *
+ * const episodes = await episodic.getEpisodes('agent_123', { limit: 10 })
+ * ```
+ */
+export class EpisodicMemory {
+  /** GraphDB instance for storage */
+  graphDb: GraphDB | null
+  /** RDF namespace for episodes */
+  namespace: string
+
+  constructor(graphDb: GraphDB | null, namespace?: string)
+
+  /** Store an execution episode */
+  storeEpisode(agentId: string, execution: {
+    id: string
+    prompt: string
+    durationMs?: number
+    success: boolean
+  }): Promise<{ episodeUri: string; timestamp: string; stored: boolean }>
+
+  /** Store a tool invocation within an episode */
+  storeToolInvocation(episodeId: string, toolName: string, args: unknown, result: unknown, success: boolean): Promise<string>
+
+  /** Retrieve episodes for an agent */
+  getEpisodes(agentId: string, options?: {
+    limit?: number
+    since?: string
+  }): Promise<Array<{
+    episode: string
+    prompt: string
+    timestamp: string
+    durationMs: number
+    success: boolean
+  }>>
+
+  /** Get episodes similar to a prompt */
+  getSimilarEpisodes(prompt: string, k?: number, threshold?: number): Promise<Array<unknown>>
+
+  /** Calculate recency score with exponential decay */
+  calculateRecencyScore(timestamp: string, decayRate?: number): number
+
+  /** Get episode count */
+  getEpisodeCount(): number
+}
+
+/**
+ * LongTermMemory - Source-of-truth Knowledge Graph
+ *
+ * Read-only access to the ingestion graph (source of truth):
+ * - Domain ontologies and schemas
+ * - Factual knowledge from data ingestion
+ * - Business rules and constraints
+ * - Clear separation from agent memory
+ *
+ * @example
+ * ```typescript
+ * const db = new GraphDB('http://example.org/source')
+ * const longTerm = new LongTermMemory(db, {
+ *   sourceGraphUri: 'http://source.ai/graph/',
+ *   agentGraphUri: 'http://agent.ai/graph/'
+ * })
+ *
+ * const facts = await longTerm.getEntityFacts('http://example.org/claim/123')
+ * const schema = await longTerm.getSchema()
+ * ```
+ */
+export class LongTermMemory {
+  /** GraphDB instance */
+  graphDb: GraphDB | null
+  /** Source graph URI (read-only truth) */
+  sourceGraphUri: string
+  /** Agent graph URI (writable) */
+  agentGraphUri: string
+  /** Read-only mode flag */
+  readOnly: boolean
+  /** Access log for audit */
+  accessLog: Array<{ operation: string; details: string; timestamp: string }>
+
+  constructor(graphDb: GraphDB | null, config?: {
+    sourceGraphUri?: string
+    agentGraphUri?: string
+    readOnly?: boolean
+  })
+
+  /** Query the source-of-truth graph (read-only) */
+  querySource(sparql: string): Promise<Array<Record<string, unknown>>>
+
+  /** Get entity facts from source graph */
+  getEntityFacts(entityUri: string, limit?: number): Promise<Array<Record<string, unknown>>>
+
+  /** Get entities by type from source graph */
+  getEntitiesByType(typeUri: string, limit?: number): Promise<Array<Record<string, unknown>>>
+
+  /** Get related entities (1-hop neighbors) */
+  getRelatedEntities(entityUri: string, direction?: 'in' | 'out' | 'both'): Promise<Array<Record<string, unknown>>>
+
+  /** Get schema/ontology information */
+  getSchema(prefix?: string | null): Promise<Array<Record<string, unknown>>>
+
+  /** Get access log */
+  getAccessLog(limit?: number): Array<{ operation: string; details: string; timestamp: string }>
+
+  /** Get graph URIs with separation explanation */
+  getGraphUris(): {
+    source: string
+    agent: string
+    separation: string
+  }
+}
+
+/**
+ * MemoryManager configuration
+ */
+export interface MemoryManagerConfig {
+  /** GraphDB instance for episodic and long-term memory */
+  graphDb?: GraphDB | null
+  /** Working memory capacity */
+  workingCapacity?: number
+  /** Episodic memory namespace */
+  episodicNamespace?: string
+  /** Source graph URI */
+  sourceGraphUri?: string
+  /** Agent graph URI */
+  agentGraphUri?: string
+  /** Retrieval weights */
+  weights?: RetrievalWeights
+}
+
+/**
+ * Memory retrieval results
+ */
+export interface MemoryRetrievalResults {
+  working: Array<{ type: string; data: unknown; score: number; source?: string }>
+  episodic: Array<{ episode: string; prompt: string; timestamp: string; score: number; source: string }>
+  longTerm: Array<Record<string, unknown> & { score: number; source: string }>
+  combined: Array<{ score: number; source: string; [key: string]: unknown }>
+}
+
+/**
+ * MemoryManager - Unified memory retrieval with weighted scoring
+ *
+ * Orchestrates all memory layers with intelligent retrieval:
+ * - Score = α × Recency + β × Relevance + γ × Importance
+ * - α = 0.3 (time decay), β = 0.5 (semantic similarity), γ = 0.2 (access frequency)
+ *
+ * @example
+ * ```typescript
+ * const runtime = new AgentRuntime({ name: 'test' })
+ * runtime.ready()
+ *
+ * const manager = new MemoryManager(runtime, {
+ *   graphDb: new GraphDB('http://example.org'),
+ *   weights: { recency: 0.3, relevance: 0.5, importance: 0.2 }
+ * })
+ *
+ * // Add to working memory
+ * manager.addToWorking({ type: 'query', content: 'find claims' })
+ *
+ * // Unified retrieval across all layers
+ * const results = await manager.retrieve('fraud claims', {
+ *   includeEpisodic: true,
+ *   includeLongTerm: true,
+ *   entityUri: 'http://example.org/claim/123'
+ * })
+ *
+ * console.log(results.combined) // Ranked results from all layers
+ * ```
+ */
+export class MemoryManager {
+  /** Associated agent runtime */
+  runtime: AgentRuntime
+  /** Working memory layer */
+  working: WorkingMemory
+  /** Episodic memory layer */
+  episodic: EpisodicMemory
+  /** Long-term memory layer */
+  longTerm: LongTermMemory
+  /** Retrieval weights */
+  weights: RetrievalWeights
+  /** Retrieval history */
+  retrievalHistory: Array<{ query: string; timestamp: number; counts: Record<string, number> }>
+
+  constructor(runtime: AgentRuntime, config?: MemoryManagerConfig)
+
+  /** Unified memory retrieval with weighted scoring */
+  retrieve(query: string, options?: {
+    includeEpisodic?: boolean
+    includeLongTerm?: boolean
+    entityUri?: string
+  }): Promise<MemoryRetrievalResults>
+
+  /** Store execution in episodic memory */
+  storeExecution(execution: {
+    id: string
+    prompt: string
+    success: boolean
+    durationMs?: number
+  }): Promise<{ episodeUri: string; timestamp: string; stored: boolean }>
+
+  /** Add item to working memory */
+  addToWorking(item: Record<string, unknown>): this
+
+  /** Get memory statistics */
+  getStats(): {
+    working: { contextSize: number; bindingsCount: number; toolResultsCount: number }
+    episodic: { episodeCount: number }
+    longTerm: { accessLogSize: number }
+    retrieval: { totalRetrievals: number; uniqueAccessedItems: number }
+    weights: RetrievalWeights
+  }
+
+  /** Clear working memory (episodic and long-term persist) */
+  clearWorking(): this
+}
+
+// ==============================================
+// Governance Layer (v0.5.13+) - Policy Engine
+// ==============================================
+
+/**
+ * GovernancePolicy configuration
+ */
+export interface GovernancePolicyConfig {
+  /** Policy name */
+  name?: string
+  /** Policy version */
+  version?: string
+  /** Granted capabilities */
+  capabilities?: string[]
+  /** Resource limits */
+  limits?: {
+    maxExecutionTimeMs?: number
+    maxMemoryMB?: number
+    maxToolCalls?: number
+    maxGraphQueries?: number
+  }
+  /** Audit settings */
+  audit?: {
+    logAllToolCalls?: boolean
+    logMemoryAccess?: boolean
+    logGraphQueries?: boolean
+    retentionDays?: number
+  }
+  /** Behavioral constraints */
+  constraints?: {
+    allowExternalApi?: boolean
+    allowFileAccess?: boolean
+    requireApprovalForWrites?: boolean
+  }
+}
+
+/**
+ * GovernancePolicy - Access control and behavioral policies
+ *
+ * @example
+ * ```typescript
+ * const policy = new GovernancePolicy({
+ *   name: 'production-policy',
+ *   capabilities: ['ReadKG', 'ExecuteTool'],
+ *   limits: { maxToolCalls: 100, maxGraphQueries: 1000 },
+ *   constraints: { allowExternalApi: false }
+ * })
+ *
+ * policy.grantCapability('AccessMemory')
+ * console.log(policy.hasCapability('WriteKG')) // false
+ * ```
+ */
+export class GovernancePolicy {
+  /** Policy name */
+  name: string
+  /** Policy version */
+  version: string
+  /** Granted capabilities */
+  capabilities: Set<string>
+  /** Resource limits */
+  limits: Record<string, number>
+  /** Audit settings */
+  audit: Record<string, unknown>
+  /** Behavioral constraints */
+  constraints: Record<string, boolean>
+
+  constructor(config?: GovernancePolicyConfig)
+
+  /** Check if capability is granted */
+  hasCapability(capability: string): boolean
+
+  /** Grant a capability */
+  grantCapability(capability: string): this
+
+  /** Revoke a capability */
+  revokeCapability(capability: string): this
+
+  /** Check resource limit */
+  checkLimit(resource: string, current: number): boolean
+
+  /** Export policy configuration */
+  export(): GovernancePolicyConfig
+}
+
+/**
+ * Authorization result
+ */
+export interface AuthorizationResult {
+  allowed: boolean
+  reason: string
+  capability?: string
+  timestamp: string
+}
+
+/**
+ * GovernanceEngine - Policy enforcement and audit logging
+ *
+ * @example
+ * ```typescript
+ * const policy = new GovernancePolicy({ capabilities: ['ReadKG'] })
+ * const engine = new GovernanceEngine(policy)
+ *
+ * const result = engine.authorize({
+ *   capability: 'WriteKG',
+ *   type: 'graphUpdate'
+ * })
+ *
+ * console.log(result.allowed) // false
+ * console.log(result.reason)  // "Missing capability: WriteKG"
+ * ```
+ */
+export class GovernanceEngine {
+  /** Active policy */
+  policy: GovernancePolicy
+  /** Audit log */
+  auditLog: Array<{ action: unknown; result: AuthorizationResult; timestamp: string }>
+  /** Denial log */
+  denials: Array<{ action: unknown; reason: string; timestamp: string }>
+
+  constructor(policy?: GovernancePolicy | null)
+
+  /** Authorize an action */
+  authorize(action: {
+    capability?: string
+    type?: string
+    resource?: string
+    current?: number
+  }): AuthorizationResult
+
+  /** Get audit log */
+  getAuditLog(limit?: number): Array<{ action: unknown; result: AuthorizationResult; timestamp: string }>
+
+  /** Get denial log */
+  getDenials(limit?: number): Array<{ action: unknown; reason: string; timestamp: string }>
+
+  /** Update policy */
+  setPolicy(policy: GovernancePolicy): this
+}
+
+// ==============================================
+// Scope Layer (v0.5.13+) - Namespace Isolation
+// ==============================================
+
+/**
+ * AgentScope configuration
+ */
+export interface AgentScopeConfig {
+  /** Scope ID (auto-generated if not provided) */
+  id?: string
+  /** Scope name */
+  name?: string
+  /** Namespace configuration */
+  namespace?: {
+    prefix?: string
+    graphUri?: string
+    allowedGraphs?: string[]
+    deniedGraphs?: string[]
+  }
+  /** Maximum memory in MB */
+  maxMemoryMB?: number
+  /** Maximum execution time in ms */
+  maxExecutionTimeMs?: number
+  /** Maximum tool calls */
+  maxToolCalls?: number
+  /** Maximum graph queries */
+  maxGraphQueries?: number
+  /** Maximum episodes */
+  maxEpisodes?: number
+  /** Share memory with other scopes */
+  shareMemory?: boolean
+  /** Share episodes with other scopes */
+  shareEpisodes?: boolean
+  /** Parent scope ID */
+  parentScope?: string | null
+}
+
+/**
+ * AgentScope - Namespace isolation and resource limits
+ *
+ * @example
+ * ```typescript
+ * const scope = new AgentScope({
+ *   name: 'fraud-detection',
+ *   maxToolCalls: 100,
+ *   namespace: {
+ *     allowedGraphs: ['http://insurance.example.org/*'],
+ *     deniedGraphs: ['http://secret.graph/']
+ *   }
+ * })
+ *
+ * scope.trackUsage('toolCalls', 5)
+ * console.log(scope.isWithinLimits('toolCalls')) // true
+ *
+ * const remaining = scope.getRemainingResources()
+ * console.log(remaining.toolcalls) // 95
+ * ```
+ */
+export class AgentScope {
+  /** Scope unique identifier */
+  id: string
+  /** Scope name */
+  name: string
+  /** Namespace configuration */
+  namespace: {
+    prefix: string
+    graphUri: string
+    allowedGraphs: string[]
+    deniedGraphs: string[]
+  }
+  /** Resource limits */
+  resources: {
+    maxMemoryMB: number
+    maxExecutionTimeMs: number
+    maxToolCalls: number
+    maxGraphQueries: number
+    maxEpisodes: number
+  }
+  /** Current usage */
+  usage: {
+    memoryMB: number
+    executionTimeMs: number
+    toolCalls: number
+    graphQueries: number
+    episodes: number
+  }
+  /** Isolation settings */
+  isolation: {
+    shareMemory: boolean
+    shareEpisodes: boolean
+    parentScope: string | null
+  }
+
+  constructor(config?: AgentScopeConfig)
+
+  /** Check if graph access is allowed */
+  isGraphAllowed(graphUri: string): boolean
+
+  /** Track resource usage */
+  trackUsage(resource: string, amount: number): this
+
+  /** Check if within resource limits */
+  isWithinLimits(resource: string): boolean
+
+  /** Get remaining resources */
+  getRemainingResources(): Record<string, number>
+
+  /** Reset usage counters */
+  resetUsage(): this
+
+  /** Get scoped graph URI for agent */
+  getScopedGraphUri(suffix?: string): string
+
+  /** Export scope configuration */
+  export(): {
+    id: string
+    name: string
+    namespace: {
+      prefix: string
+      graphUri: string
+      allowedGraphs: string[]
+      deniedGraphs: string[]
+    }
+    resources: {
+      maxMemoryMB: number
+      maxExecutionTimeMs: number
+      maxToolCalls: number
+      maxGraphQueries: number
+      maxEpisodes: number
+    }
+    usage: Record<string, number>
+    isolation: {
+      shareMemory: boolean
+      shareEpisodes: boolean
+      parentScope: string | null
+    }
+  }
+}