@micrantha/react-native-amaryllis 0.1.0 → 0.1.5

package/src/AmaryllisHooks.tsx

@@ -1,7 +1,42 @@
 import { useCallback, useMemo, useEffect } from 'react';
-import type { LlmRequestParams, InferenceProps } from './Types';
+import type { InferenceProps, LlmRequestParams } from './Types';
 import { useLLMContext } from './AmaryllisContext';
 import { createLLMObservable } from './AmaryllisRx';
+import { useContextEngine } from './ContextEngineContext';
+import type { ContextEngine, ContextQuery } from './ContextTypes';
+
+export type ContextInferenceProps = InferenceProps & {
+  contextEngine?: ContextEngine;
+  query?: ContextQuery;
+};
+
+const useContextAugmentation = (
+  contextEngine?: ContextEngine,
+  query?: ContextQuery
+) => {
+  const engineFromProvider = useContextEngine();
+  const engine = contextEngine ?? engineFromProvider;
+
+  return useCallback(
+    async (params: LlmRequestParams): Promise<LlmRequestParams> => {
+      if (!engine) {
+        return params;
+      }
+      const resolvedQuery = query ?? engine.deriveQuery(params.prompt, params);
+      if (!resolvedQuery) {
+        return params;
+      }
+      const items = await engine.search(resolvedQuery);
+      return engine.formatRequest({
+        prompt: params.prompt,
+        items,
+        query: resolvedQuery,
+        request: params,
+      });
+    },
+    [engine, query]
+  );
+};
 
 export const useInferenceAsync = (props: InferenceProps = {}) => {
   const { controller } = useLLMContext();
@@ -11,16 +46,23 @@ export const useInferenceAsync = (props: InferenceProps = {}) => {
 
   const generate = useCallback(
     async (params: LlmRequestParams) => {
+      if (!controller) {
+        onError?.(new Error('Controller not initialized'));
+        return () => {
+          onComplete?.();
+        };
+      }
+
       try {
         onGenerate?.();
-        await controller?.generateAsync(params, llm$.callbacks);
+        await controller.generateAsync(params, llm$.callbacks);
       } catch (err) {
         onError?.(
           err instanceof Error ? err : new Error('An unknown error occurred')
         );
       }
       return () => {
-        controller?.cancelAsync();
+        controller.cancelAsync();
         onComplete?.();
       };
     },
@@ -56,9 +98,16 @@ export const useInference = (props: InferenceProps = {}) => {
 
   const generate = useCallback(
     async (params: LlmRequestParams) => {
+      if (!controller) {
+        onError?.(new Error('Controller not initialized'));
+        return () => {
+          onComplete?.();
+        };
+      }
+
       try {
         onGenerate?.();
-        const response = await controller?.generate(params);
+        const response = await controller.generate(params);
         onResult?.(response ?? '', true);
       } catch (err) {
         onError?.(
@@ -67,7 +116,7 @@ export const useInference = (props: InferenceProps = {}) => {
       }
 
       return () => {
-        controller?.cancelAsync();
+        controller.cancelAsync();
         onComplete?.();
       };
     },
@@ -76,3 +125,55 @@ export const useInference = (props: InferenceProps = {}) => {
 
   return generate;
 };
+
+export const useContextInferenceAsync = (props: ContextInferenceProps = {}) => {
+  const { contextEngine, query, ...inferenceProps } = props;
+  const { onComplete, onError } = inferenceProps;
+  const augmentRequest = useContextAugmentation(contextEngine, query);
+  const generateBase = useInferenceAsync(inferenceProps);
+
+  const generate = useCallback(
+    async (params: LlmRequestParams) => {
+      try {
+        const augmented = await augmentRequest(params);
+        return await generateBase(augmented);
+      } catch (err) {
+        onError?.(
+          err instanceof Error ? err : new Error('An unknown error occurred')
+        );
+        return () => {
+          onComplete?.();
+        };
+      }
+    },
+    [augmentRequest, generateBase, onComplete, onError]
+  );
+
+  return generate;
+};
+
+export const useContextInference = (props: ContextInferenceProps = {}) => {
+  const { contextEngine, query, ...inferenceProps } = props;
+  const { onComplete, onError } = inferenceProps;
+  const augmentRequest = useContextAugmentation(contextEngine, query);
+  const generateBase = useInference(inferenceProps);
+
+  const generate = useCallback(
+    async (params: LlmRequestParams) => {
+      try {
+        const augmented = await augmentRequest(params);
+        return await generateBase(augmented);
+      } catch (err) {
+        onError?.(
+          err instanceof Error ? err : new Error('An unknown error occurred')
+        );
+        return () => {
+          onComplete?.();
+        };
+      }
+    },
+    [augmentRequest, generateBase, onComplete, onError]
+  );
+
+  return generate;
+};

package/src/AmaryllisRx.ts

@@ -2,21 +2,25 @@ import type { LlmCallbacks, LLMObservableResult, LLMResult } from './Types';
 import { Observable, Subscriber } from 'rxjs';
 
 export function createLLMObservable(): LLMObservableResult {
-  let subscriber: Subscriber<LLMResult>;
+  let subscriber: Subscriber<LLMResult> | null = null;
 
   const observable = new Observable<LLMResult>((sub) => {
     subscriber = sub;
+    return () => {
+      subscriber = null;
+    };
   });
 
   const callbacks: LlmCallbacks = {
-    onPartialResult: (partial) => {
-      subscriber?.next({ text: partial, isFinal: false });
-    },
-    onFinalResult: (final) => {
-      subscriber?.next({ text: final, isFinal: true });
-    },
-    onError: (error) => {
-      subscriber?.error(error);
+    onEvent: (event) => {
+      if (!subscriber) {
+        return;
+      }
+      if (event.type === 'error') {
+        subscriber.error(event.error);
+        return;
+      }
+      subscriber.next({ text: event.text, isFinal: event.type === 'final' });
     },
   };
 

package/src/ContextEngine.ts

@@ -0,0 +1,133 @@
+import type {
+  ContextEngine as ContextEngineContract,
+  ContextEngineOptions,
+  ContextFormatParams,
+  ContextItem,
+  ContextQuery,
+  ContextScorer,
+  ContextDefaultQueryFactory,
+  ContextRequestFormatter,
+} from './ContextTypes';
+import type { LlmRequestParams } from './Types';
+import { defaultContextScorer } from './ContextPolicies';
+import {
+  validateContextItems,
+  validateContextPolicy,
+  validateContextQuery,
+} from './ContextValidation';
+
+const formatMetadata = (metadata: ContextItem['metadata']): string | null => {
+  if (!metadata) {
+    return null;
+  }
+  const entries = Object.entries(metadata);
+  if (entries.length === 0) {
+    return null;
+  }
+  const pairs = entries.map(([key, value]) => `${key}=${value}`);
+  return `meta=${pairs.join(', ')}`;
+};
+
+const formatTags = (tags: ContextItem['tags']): string | null => {
+  if (!tags || tags.length === 0) {
+    return null;
+  }
+  return `tags=${tags.join(', ')}`;
+};
+
+const formatContextItem = (item: ContextItem): string => {
+  const parts = [
+    item.text.trim(),
+    formatTags(item.tags),
+    formatMetadata(item.metadata),
+  ];
+  return parts
+    .filter((part): part is string => Boolean(part && part.length > 0))
+    .join(' | ');
+};
+
+export const defaultContextFormatter: ContextRequestFormatter = (
+  params: ContextFormatParams
+) => {
+  if (params.items.length === 0) {
+    return params.request;
+  }
+  const lines = params.items.map((item) => `- ${formatContextItem(item)}`);
+  const contextBlock = ['Context:', ...lines].join('\n');
+  const augmentedPrompt = [contextBlock, params.prompt]
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .join('\n\n');
+  return {
+    ...params.request,
+    prompt: augmentedPrompt,
+  };
+};
+
+export class ContextEngine implements ContextEngineContract {
+  private readonly store: ContextEngineOptions['store'];
+  private readonly scorer: ContextScorer;
+  private policy: ContextEngineOptions['policy'];
+  private readonly formatter: ContextRequestFormatter;
+  private readonly defaultQueryFactory?: ContextDefaultQueryFactory;
+
+  constructor(options: ContextEngineOptions) {
+    validateContextPolicy(options.policy);
+    this.store = options.store;
+    this.scorer = options.scorer ?? defaultContextScorer;
+    this.policy = options.policy ?? {};
+    this.formatter = options.formatter ?? defaultContextFormatter;
+    this.defaultQueryFactory = options.defaultQueryFactory;
+  }
+
+  async add(items: ContextItem[]): Promise<void> {
+    validateContextItems(items, this.policy);
+    await this.store.put(items);
+  }
+
+  async search(query: ContextQuery): Promise<ContextItem[]> {
+    validateContextQuery(query);
+    const results = await this.store.query(query);
+    if (results.length <= 1) {
+      return results;
+    }
+    const scored = results.map((item, index) => ({
+      item,
+      index,
+      score: this.scorer.score(item, query),
+    }));
+    scored.sort((a, b) => {
+      if (a.score === b.score) {
+        return a.index - b.index;
+      }
+      return b.score - a.score;
+    });
+    return scored.map((entry) => entry.item);
+  }
+
+  setPolicy(policy: ContextEngineOptions['policy']): void {
+    validateContextPolicy(policy);
+    this.policy = policy ?? {};
+  }
+
+  async compact(): Promise<void> {
+    await this.store.compact(this.policy ?? {});
+  }
+
+  formatRequest(params: ContextFormatParams): LlmRequestParams {
+    return this.formatter(params);
+  }
+
+  deriveQuery(
+    prompt: string,
+    request: LlmRequestParams
+  ): ContextQuery | undefined {
+    return this.defaultQueryFactory?.(prompt, request);
+  }
+}
+
+export const createContextEngine = (
+  options: ContextEngineOptions
+): ContextEngineContract => {
+  return new ContextEngine(options);
+};

package/src/ContextEngineContext.tsx

@@ -0,0 +1,31 @@
+import { createContext, useContext } from 'react';
+import type { ReactNode } from 'react';
+import type { ContextEngine } from './ContextTypes';
+
+export interface ContextEngineProviderProps {
+  engine: ContextEngine;
+  children: ReactNode;
+}
+
+interface ContextEngineContextValue {
+  engine: ContextEngine | null;
+}
+
+const ContextEngineContext = createContext<ContextEngineContextValue>({
+  engine: null,
+});
+
+export const ContextEngineProvider = ({
+  engine,
+  children,
+}: ContextEngineProviderProps) => {
+  return (
+    <ContextEngineContext.Provider value={{ engine }}>
+      {children}
+    </ContextEngineContext.Provider>
+  );
+};
+
+export const useContextEngine = (): ContextEngine | null => {
+  return useContext(ContextEngineContext).engine;
+};

package/src/ContextPolicies.ts

@@ -0,0 +1,54 @@
+import type { ContextItem, ContextQuery, ContextScorer } from './ContextTypes';
+
+export const DEFAULT_RECENCY_BIAS = 0.35;
+
+const clamp01 = (value: number): number => {
+  if (value < 0) {
+    return 0;
+  }
+  if (value > 1) {
+    return 1;
+  }
+  return value;
+};
+
+const tokenize = (text: string): string[] => {
+  return text
+    .toLowerCase()
+    .split(/\\s+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+};
+
+const keywordScore = (item: ContextItem, query: ContextQuery): number => {
+  const queryTokens = tokenize(query.text);
+  if (queryTokens.length === 0) {
+    return 0;
+  }
+  const haystack = item.text.toLowerCase();
+  let hits = 0;
+  for (const token of queryTokens) {
+    if (haystack.includes(token)) {
+      hits += 1;
+    }
+  }
+  return hits / queryTokens.length;
+};
+
+const recencyScore = (item: ContextItem): number => {
+  const ageMs = Date.now() - item.createdAt;
+  if (!Number.isFinite(ageMs) || ageMs < 0) {
+    return 0;
+  }
+  const ageHours = ageMs / (1000 * 60 * 60);
+  return 1 / (1 + ageHours);
+};
+
+export const defaultContextScorer: ContextScorer = {
+  score: (item: ContextItem, query: ContextQuery): number => {
+    const bias = clamp01(query.recencyBias ?? DEFAULT_RECENCY_BIAS);
+    const recency = recencyScore(item);
+    const keyword = keywordScore(item, query);
+    return bias * recency + (1 - bias) * keyword;
+  },
+};

package/src/ContextTypes.ts

@@ -0,0 +1,122 @@
+import type { LlmRequestParams } from './Types';
+
+export type EvictionStrategy = 'lru' | 'recency' | 'size';
+
+export interface MediaReference {
+  // Absolute path or URI depending on app policy.
+  uri: string;
+  mimeType?: string;
+  sizeBytes?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface MediaValidationPolicy {
+  // Require absolute URIs (recommended for security).
+  requireAbsoluteUri?: boolean;
+  // Whitelist of allowed URI schemes (e.g., ['file', 'content']).
+  allowedUriSchemes?: string[];
+  // Size and dimension limits for referenced media.
+  maxMediaBytes?: number;
+  maxMediaWidth?: number;
+  maxMediaHeight?: number;
+}
+
+export interface ContextItem {
+  id: string;
+  text: string;
+  metadata?: Record<string, string>;
+  tags?: string[];
+  media?: MediaReference[];
+  createdAt: number;
+  updatedAt?: number;
+  ttlSeconds?: number;
+}
+
+export interface ContextQuery {
+  text: string;
+  limit?: number;
+  filters?: Record<string, string>;
+  tags?: string[];
+  // 0..1 weighting for recency in scoring.
+  recencyBias?: number;
+  useSemantic?: boolean;
+}
+
+export interface ContextPolicy {
+  maxBytes?: number;
+  maxItems?: number;
+  defaultTtlSeconds?: number;
+  evictionStrategy?: EvictionStrategy;
+  media?: MediaValidationPolicy;
+}
+
+export interface ContextStoreStats {
+  itemCount: number;
+  totalBytes?: number;
+}
+
+export interface ContextStore {
+  put(items: ContextItem[]): Promise<void>;
+  query(query: ContextQuery): Promise<ContextItem[]>;
+  delete(ids: string[]): Promise<void>;
+  compact(policy: ContextPolicy): Promise<void>;
+  stats(): Promise<ContextStoreStats>;
+}
+
+export interface EmbeddingProvider {
+  embed(texts: string[]): Promise<number[][]>;
+  dimension?: number;
+}
+
+export interface ContextEngine {
+  add(items: ContextItem[]): Promise<void>;
+  search(query: ContextQuery): Promise<ContextItem[]>;
+  setPolicy(policy: ContextPolicy): void;
+  compact(): Promise<void>;
+  formatRequest(params: ContextFormatParams): LlmRequestParams;
+  deriveQuery(
+    prompt: string,
+    request: LlmRequestParams
+  ): ContextQuery | undefined;
+}
+
+export interface ContextScorer {
+  score(item: ContextItem, query: ContextQuery): number;
+}
+
+export interface ContextEngineOptions {
+  store: ContextStore;
+  scorer?: ContextScorer;
+  policy?: ContextPolicy;
+  formatter?: ContextRequestFormatter;
+  defaultQueryFactory?: ContextDefaultQueryFactory;
+}
+
+export interface ContextFormatParams {
+  prompt: string;
+  items: ContextItem[];
+  query?: ContextQuery;
+  request: LlmRequestParams;
+}
+
+export type ContextRequestFormatter = (
+  params: ContextFormatParams
+) => LlmRequestParams;
+
+export type ContextDefaultQueryFactory = (
+  prompt: string,
+  request: LlmRequestParams
+) => ContextQuery | undefined;
+
+export interface ToolDefinition {
+  name: string;
+  description?: string;
+  // JSON schema or similar contract for tool input.
+  inputSchema?: Record<string, unknown>;
+}
+
+export interface ToolRegistry {
+  register(tool: ToolDefinition): void;
+  invoke(name: string, input: unknown): Promise<unknown>;
+}