@micrantha/react-native-amaryllis 0.1.0 → 0.1.5

package/src/ContextValidation.ts

@@ -0,0 +1,279 @@
+import type {
+  ContextItem,
+  ContextPolicy,
+  ContextQuery,
+  MediaReference,
+  MediaValidationPolicy,
+} from './ContextTypes';
+import { ValidationError } from './Errors';
+
+const SCHEME_REGEX = /^([a-zA-Z][a-zA-Z0-9+.-]*):/;
+
+const isAbsolutePath = (uri: string): boolean => {
+  return uri.startsWith('/') || /^[a-zA-Z]:\\\\/.test(uri);
+};
+
+const getScheme = (uri: string): string | undefined => {
+  const match = uri.match(SCHEME_REGEX);
+  return match?.[1]?.toLowerCase();
+};
+
+const isPositiveNumber = (value: number | undefined): value is number => {
+  return value !== undefined && Number.isFinite(value) && value > 0;
+};
+
+const isNonEmptyString = (value: string | undefined): value is string => {
+  return value !== undefined && value.trim().length > 0;
+};
+
+const assertNonEmpty = (value: string, field: string): void => {
+  if (!isNonEmptyString(value)) {
+    throw new ValidationError(`${field} must be a non-empty string`);
+  }
+};
+
+const validateStringList = (values: string[], field: string): void => {
+  if (values.length === 0) {
+    throw new ValidationError(`${field} must not be empty`);
+  }
+  for (const value of values) {
+    assertNonEmpty(value, field);
+  }
+};
+
+export const validateContextPolicy = (
+  policy: ContextPolicy | undefined
+): void => {
+  if (!policy) {
+    return;
+  }
+
+  const { maxBytes, maxItems, defaultTtlSeconds, evictionStrategy, media } =
+    policy;
+
+  if (maxBytes !== undefined && !isPositiveNumber(maxBytes)) {
+    throw new ValidationError('maxBytes must be a positive number');
+  }
+  if (maxItems !== undefined && !isPositiveNumber(maxItems)) {
+    throw new ValidationError('maxItems must be a positive number');
+  }
+  if (defaultTtlSeconds !== undefined && !isPositiveNumber(defaultTtlSeconds)) {
+    throw new ValidationError('defaultTtlSeconds must be a positive number');
+  }
+  const hasEvictionStrategy = Object.prototype.hasOwnProperty.call(
+    policy,
+    'evictionStrategy'
+  );
+  if (hasEvictionStrategy && evictionStrategy === undefined) {
+    throw new ValidationError('evictionStrategy is not supported');
+  }
+  if (
+    evictionStrategy !== undefined &&
+    evictionStrategy !== 'lru' &&
+    evictionStrategy !== 'recency' &&
+    evictionStrategy !== 'size'
+  ) {
+    throw new ValidationError('evictionStrategy is not supported');
+  }
+
+  validateMediaPolicy(media);
+};
+
+export const validateMediaPolicy = (
+  policy: MediaValidationPolicy | undefined
+): void => {
+  if (!policy) {
+    return;
+  }
+
+  const { allowedUriSchemes, maxMediaBytes, maxMediaWidth, maxMediaHeight } =
+    policy;
+
+  if (allowedUriSchemes) {
+    if (allowedUriSchemes.length === 0) {
+      throw new ValidationError('allowedUriSchemes must not be empty');
+    }
+    for (const scheme of allowedUriSchemes) {
+      assertNonEmpty(scheme, 'allowedUriSchemes item');
+    }
+  }
+
+  if (maxMediaBytes !== undefined && !isPositiveNumber(maxMediaBytes)) {
+    throw new ValidationError('maxMediaBytes must be a positive number');
+  }
+  if (maxMediaWidth !== undefined && !isPositiveNumber(maxMediaWidth)) {
+    throw new ValidationError('maxMediaWidth must be a positive number');
+  }
+  if (maxMediaHeight !== undefined && !isPositiveNumber(maxMediaHeight)) {
+    throw new ValidationError('maxMediaHeight must be a positive number');
+  }
+};
+
+export const validateMediaReference = (
+  reference: MediaReference,
+  policy?: MediaValidationPolicy
+): void => {
+  assertNonEmpty(reference.uri, 'MediaReference.uri');
+
+  if (policy?.requireAbsoluteUri) {
+    const scheme = getScheme(reference.uri);
+    if (!scheme && !isAbsolutePath(reference.uri)) {
+      throw new ValidationError(
+        'MediaReference.uri must be an absolute path or URI'
+      );
+    }
+  }
+
+  if (policy?.allowedUriSchemes) {
+    const scheme = getScheme(reference.uri);
+    if (!scheme) {
+      throw new ValidationError(
+        'MediaReference.uri must include a scheme when allowedUriSchemes is set'
+      );
+    }
+    const allowed = policy.allowedUriSchemes.map((item) => item.toLowerCase());
+    if (!allowed.includes(scheme)) {
+      throw new ValidationError(
+        `MediaReference.uri scheme not allowed: ${scheme}`
+      );
+    }
+  }
+
+  if (
+    reference.sizeBytes !== undefined &&
+    !isPositiveNumber(reference.sizeBytes)
+  ) {
+    throw new ValidationError(
+      'MediaReference.sizeBytes must be a positive number'
+    );
+  }
+  if (reference.width !== undefined && !isPositiveNumber(reference.width)) {
+    throw new ValidationError('MediaReference.width must be a positive number');
+  }
+  if (reference.height !== undefined && !isPositiveNumber(reference.height)) {
+    throw new ValidationError(
+      'MediaReference.height must be a positive number'
+    );
+  }
+
+  if (
+    policy?.maxMediaBytes !== undefined &&
+    reference.sizeBytes !== undefined &&
+    reference.sizeBytes > policy.maxMediaBytes
+  ) {
+    throw new ValidationError(
+      'MediaReference.sizeBytes exceeds policy maxMediaBytes'
+    );
+  }
+  if (
+    policy?.maxMediaWidth !== undefined &&
+    reference.width !== undefined &&
+    reference.width > policy.maxMediaWidth
+  ) {
+    throw new ValidationError(
+      'MediaReference.width exceeds policy maxMediaWidth'
+    );
+  }
+  if (
+    policy?.maxMediaHeight !== undefined &&
+    reference.height !== undefined &&
+    reference.height > policy.maxMediaHeight
+  ) {
+    throw new ValidationError(
+      'MediaReference.height exceeds policy maxMediaHeight'
+    );
+  }
+};
+
+export const validateMediaReferences = (
+  references: MediaReference[] | undefined,
+  policy?: MediaValidationPolicy
+): void => {
+  if (!references) {
+    return;
+  }
+  if (references.length === 0) {
+    throw new ValidationError('media must not be an empty array');
+  }
+  validateMediaPolicy(policy);
+  for (const reference of references) {
+    validateMediaReference(reference, policy);
+  }
+};
+
+export const validateContextItem = (
+  item: ContextItem,
+  policy?: ContextPolicy
+): void => {
+  assertNonEmpty(item.id, 'ContextItem.id');
+  assertNonEmpty(item.text, 'ContextItem.text');
+
+  if (!Number.isFinite(item.createdAt) || item.createdAt <= 0) {
+    throw new ValidationError(
+      'ContextItem.createdAt must be a positive number'
+    );
+  }
+  if (
+    item.updatedAt !== undefined &&
+    (!Number.isFinite(item.updatedAt) || item.updatedAt <= 0)
+  ) {
+    throw new ValidationError(
+      'ContextItem.updatedAt must be a positive number'
+    );
+  }
+  if (item.ttlSeconds !== undefined && !isPositiveNumber(item.ttlSeconds)) {
+    throw new ValidationError(
+      'ContextItem.ttlSeconds must be a positive number'
+    );
+  }
+
+  if (item.tags) {
+    validateStringList(item.tags, 'ContextItem.tags');
+  }
+
+  if (item.metadata) {
+    const entries = Object.entries(item.metadata);
+    for (const [key, value] of entries) {
+      assertNonEmpty(key, 'ContextItem.metadata key');
+      assertNonEmpty(value, 'ContextItem.metadata value');
+    }
+  }
+
+  validateMediaReferences(item.media, policy?.media);
+};
+
+export const validateContextItems = (
+  items: ContextItem[],
+  policy?: ContextPolicy
+): void => {
+  if (items.length === 0) {
+    throw new ValidationError('items must not be empty');
+  }
+  validateContextPolicy(policy);
+  for (const item of items) {
+    validateContextItem(item, policy);
+  }
+};
+
+export const validateContextQuery = (query: ContextQuery): void => {
+  assertNonEmpty(query.text, 'ContextQuery.text');
+
+  if (query.limit !== undefined && !isPositiveNumber(query.limit)) {
+    throw new ValidationError('ContextQuery.limit must be a positive number');
+  }
+  if (query.recencyBias !== undefined && !Number.isFinite(query.recencyBias)) {
+    throw new ValidationError(
+      'ContextQuery.recencyBias must be a finite number'
+    );
+  }
+  if (query.tags) {
+    validateStringList(query.tags, 'ContextQuery.tags');
+  }
+  if (query.filters) {
+    const entries = Object.entries(query.filters);
+    for (const [key, value] of entries) {
+      assertNonEmpty(key, 'ContextQuery.filters key');
+      assertNonEmpty(value, 'ContextQuery.filters value');
+    }
+  }
+};

package/src/Errors.ts

@@ -0,0 +1,55 @@
+export class AmaryllisError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string
+  ) {
+    super(message);
+    this.name = 'AmaryllisError';
+  }
+}
+
+export class InitializationError extends AmaryllisError {
+  constructor(message: string) {
+    super(message, 'INIT_ERROR');
+    this.name = 'InitializationError';
+  }
+}
+
+export class GenerationError extends AmaryllisError {
+  constructor(message: string) {
+    super(message, 'GENERATION_ERROR');
+    this.name = 'GenerationError';
+  }
+}
+
+export class SessionError extends AmaryllisError {
+  constructor(message: string) {
+    super(message, 'SESSION_ERROR');
+    this.name = 'SessionError';
+  }
+}
+
+export class ValidationError extends AmaryllisError {
+  constructor(message: string) {
+    super(message, 'VALIDATION_ERROR');
+    this.name = 'ValidationError';
+  }
+}
+
+export class ResourceError extends AmaryllisError {
+  constructor(message: string) {
+    super(message, 'RESOURCE_ERROR');
+    this.name = 'ResourceError';
+  }
+}
+
+export function isAmaryllisError(error: unknown): error is AmaryllisError {
+  return error instanceof AmaryllisError;
+}
+
+export function createError(
+  message: string,
+  code: string = 'UNKNOWN_ERROR'
+): AmaryllisError {
+  return new AmaryllisError(message, code);
+}

package/src/NativeAmaryllis.ts

@@ -2,13 +2,27 @@ import type { TurboModule } from 'react-native';
 import { TurboModuleRegistry } from 'react-native';
 
 export interface Spec extends TurboModule {
-  init(params: Object): Promise<void>;
+  init(params: {
+    modelPath: string;
+    maxTopK?: number;
+    maxNumImages?: number;
+    maxTokens?: number;
+    visionEncoderPath?: string;
+    visionAdapterPath?: string;
+  }): Promise<void>;
 
-  newSession(params: Object): Promise<void>;
+  newSession(params?: {
+    topK?: number;
+    topP?: number;
+    temperature?: number;
+    randomSeed?: number;
+    loraPath?: string;
+    enableVisionModality?: boolean;
+  }): Promise<void>;
 
-  generate(params: Object): Promise<string>;
+  generate(params: { prompt: string; images?: string[] }): Promise<string>;
 
-  generateAsync(params: Object): Promise<void>;
+  generateAsync(params: { prompt: string; images?: string[] }): Promise<void>;
 
   close(): void;
 

package/src/TypeConverters.ts

@@ -0,0 +1,87 @@
+import type {
+  LlmEngineConfig,
+  LlmSessionParams,
+  LlmRequestParams,
+} from './Types';
+
+/**
+ * Convert rich LlmEngineConfig to codegen-compatible object structure
+ */
+export function toNativeEngineConfig(config: LlmEngineConfig) {
+  return {
+    modelPath: config.modelPath,
+    maxTopK: config.maxTopK,
+    maxNumImages: config.maxNumImages,
+    maxTokens: config.maxTokens,
+    visionEncoderPath: config.visionEncoderPath,
+    visionAdapterPath: config.visionAdapterPath,
+  };
+}
+
+/**
+ * Convert codegen-compatible config object to rich LlmEngineConfig
+ */
+export function fromNativeEngineConfig(native: any): LlmEngineConfig {
+  return {
+    modelPath: native.modelPath,
+    maxTopK: native.maxTopK,
+    maxNumImages: native.maxNumImages,
+    maxTokens: native.maxTokens,
+    visionEncoderPath: native.visionEncoderPath,
+    visionAdapterPath: native.visionAdapterPath,
+  };
+}
+
+/**
+ * Convert rich LlmSessionParams to codegen-compatible object structure
+ */
+export function toNativeSessionParams(params?: LlmSessionParams) {
+  if (!params) return undefined;
+
+  return {
+    topK: params.topK,
+    topP: params.topP,
+    temperature: params.temperature,
+    randomSeed: params.randomSeed,
+    loraPath: params.loraPath,
+    enableVisionModality: params.enableVisionModality,
+  };
+}
+
+/**
+ * Convert codegen-compatible session object to rich LlmSessionParams
+ */
+export function fromNativeSessionParams(
+  native?: any
+): LlmSessionParams | undefined {
+  if (!native) return undefined;
+
+  return {
+    topK: native.topK,
+    topP: native.topP,
+    temperature: native.temperature,
+    randomSeed: native.randomSeed,
+    loraPath: native.loraPath,
+    enableVisionModality: native.enableVisionModality,
+  };
+}
+
+/**
+ * Convert rich LlmRequestParams to codegen-compatible object structure
+ */
+export function toNativeRequestParams(params: LlmRequestParams) {
+  return {
+    prompt: params.prompt,
+    images: params.images,
+  };
+}
+
+/**
+ * Convert codegen-compatible request object to rich LlmRequestParams
+ */
+export function fromNativeRequestParams(native: any): LlmRequestParams {
+  return {
+    prompt: native.prompt,
+    images: native.images,
+  };
+}

package/src/Types.ts

@@ -3,10 +3,19 @@ import type { Observable } from 'rxjs';
 
 export type LlmNativeEngine = Spec;
 
+export type LlmEvent =
+  | { type: 'partial'; text: string }
+  | { type: 'final'; text: string }
+  | { type: 'error'; error: Error };
+
 export type LlmCallbacks = {
   // Async streaming callbacks
+  onEvent?: (event: LlmEvent) => void;
+  /** @deprecated Use onEvent instead. */
   onPartialResult?: (result: string) => void;
+  /** @deprecated Use onEvent instead. */
   onFinalResult?: (result: string) => void;
+  /** @deprecated Use onEvent instead. */
   onError?: (err: Error) => void;
 };
 

package/src/context.ts

@@ -0,0 +1,14 @@
+export {
+  ContextEngine,
+  createContextEngine,
+  defaultContextFormatter,
+} from './ContextEngine';
+export * from './ContextEngineContext';
+export * from './ContextPolicies';
+export * from './ContextValidation';
+export {
+  useContextInference,
+  useContextInferenceAsync,
+} from './AmaryllisHooks';
+export type { ContextInferenceProps } from './AmaryllisHooks';
+export type * from './ContextTypes';

package/src/index.tsx

@@ -2,4 +2,9 @@ export { default as Amaryllis, LlmPipe } from './Amaryllis';
 export * from './AmaryllisHooks';
 export * from './AmaryllisContext';
 export * from './AmaryllisRx';
+export { createContextEngine } from './ContextEngine';
+export * from './ContextEngineContext';
+export * from './ContextPolicies';
+export * from './ContextValidation';
+export type * from './ContextTypes';
 export type * from './Types';