@mxf-dev/core 1.0.0

package/dist/types/TaskTypes.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Task Management Types for the MXF Framework
+ *
+ * Defines interfaces and types for task creation, assignment, and management
+ * across channels with intelligent agent assignment using SystemLlmService
+ */
+import { AgentId } from './Agent.js';
+import { ChannelId } from './ChannelContext.js';
+/**
+ * Task priority levels
+ */
+export type TaskPriority = 'low' | 'medium' | 'high' | 'urgent';
+/**
+ * Task status states
+ */
+export type TaskStatus = 'pending' | 'assigned' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Task creation source
+ */
+export type TaskCreatedBy = 'human' | 'system' | AgentId;
+/**
+ * Agent assignment strategy types
+ */
+export type AssignmentStrategy = 'role_based' | 'workload_balanced' | 'expertise_driven' | 'manual' | 'intelligent' | 'none';
+/**
+ * Core Channel Task interface
+ */
+export interface ChannelTask {
+    id: string;
+    channelId: ChannelId;
+    title: string;
+    description: string;
+    priority: TaskPriority;
+    requiredRoles?: string[];
+    requiredCapabilities?: string[];
+    assignedAgentId?: AgentId;
+    assignedAgentIds?: AgentId[];
+    assignmentScope: 'single' | 'multiple' | 'channel-wide';
+    assignmentDistribution?: 'parallel' | 'sequential' | 'collaborative';
+    channelWideTask?: boolean;
+    targetAgentRoles?: string[];
+    excludeAgentIds?: AgentId[];
+    maxParticipants?: number;
+    coordinationMode?: 'independent' | 'collaborative' | 'sequential' | 'hierarchical';
+    leadAgentId?: AgentId;
+    agentSelectionCriteria?: {
+        minimumCapabilityMatch?: number;
+        excludeBusyAgents?: boolean;
+        preferIdleAgents?: boolean;
+        requireAllCapabilities?: boolean;
+    };
+    status: TaskStatus;
+    progress?: number;
+    createdAt: number;
+    updatedAt: number;
+    dueDate?: number;
+    estimatedDuration?: number;
+    actualDuration?: number;
+    createdBy: TaskCreatedBy;
+    metadata?: Record<string, any>;
+    tags?: string[];
+    dependsOn?: string[];
+    blockedBy?: string[];
+    result?: {
+        success?: boolean;
+        output?: any;
+        error?: string;
+        completedAt?: number;
+        completedBy?: string;
+    };
+    assignmentStrategy: AssignmentStrategy;
+}
+/**
+ * Task creation request
+ */
+export interface CreateTaskRequest {
+    channelId: ChannelId;
+    title: string;
+    description: string;
+    priority?: TaskPriority;
+    requiredRoles?: string[];
+    requiredCapabilities?: string[];
+    assignmentStrategy?: AssignmentStrategy;
+    assignedAgentId?: AgentId;
+    assignedAgentIds?: AgentId[];
+    assignmentScope?: 'single' | 'multiple' | 'channel-wide';
+    assignmentDistribution?: 'parallel' | 'sequential' | 'collaborative';
+    channelWideTask?: boolean;
+    targetAgentRoles?: string[];
+    excludeAgentIds?: AgentId[];
+    maxParticipants?: number;
+    coordinationMode?: 'independent' | 'collaborative' | 'sequential' | 'hierarchical';
+    leadAgentId?: AgentId;
+    agentSelectionCriteria?: {
+        minimumCapabilityMatch?: number;
+        excludeBusyAgents?: boolean;
+        preferIdleAgents?: boolean;
+        requireAllCapabilities?: boolean;
+    };
+    dueDate?: number;
+    estimatedDuration?: number;
+    metadata?: Record<string, any>;
+    tags?: string[];
+    dependsOn?: string[];
+}
+/**
+ * Task update request
+ */
+export interface UpdateTaskRequest {
+    status?: TaskStatus;
+    progress?: number;
+    assignedAgentId?: AgentId;
+    priority?: TaskPriority;
+    dueDate?: number;
+    metadata?: Record<string, any>;
+    tags?: string[];
+}
+/**
+ * Agent assignment analysis from SystemLLM
+ */
+export interface AgentAssignmentAnalysis {
+    recommendedAgentId: AgentId;
+    confidence: number;
+    reasoning: string;
+    roleMatch: number;
+    capabilityMatch: number;
+    workloadScore: number;
+    expertiseScore: number;
+    availabilityScore: number;
+    alternatives?: Array<{
+        agentId: AgentId;
+        confidence: number;
+        reasoning: string;
+    }>;
+}
+/**
+ * Channel workload analysis
+ */
+export interface ChannelWorkloadAnalysis {
+    channelId: ChannelId;
+    totalTasks: number;
+    pendingTasks: number;
+    activeTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    agentWorkloads: Array<{
+        agentId: AgentId;
+        activeTasks: number;
+        pendingTasks: number;
+        completionRate: number;
+        averageTaskDuration: number;
+        isOverloaded: boolean;
+    }>;
+    averageCompletionTime: number;
+    taskThroughput: number;
+    analysisTimestamp: number;
+    confidence: number;
+}
+/**
+ * Task assignment result
+ */
+export interface TaskAssignmentResult {
+    taskId: string;
+    assignedAgentId: AgentId;
+    strategy: AssignmentStrategy;
+    confidence: number;
+    reasoning: string;
+    assignedAt: number;
+    estimatedCompletion?: number;
+}
+/**
+ * Task query filters
+ */
+export interface TaskQueryFilters {
+    channelId?: ChannelId;
+    status?: TaskStatus | TaskStatus[];
+    priority?: TaskPriority | TaskPriority[];
+    assignedAgentId?: AgentId;
+    createdBy?: TaskCreatedBy;
+    tags?: string[];
+    dueBefore?: number;
+    dueAfter?: number;
+    createdBefore?: number;
+    createdAfter?: number;
+}
+/**
+ * Task orchestration configuration
+ */
+export interface TaskOrchestrationConfig {
+    enableIntelligentAssignment: boolean;
+    enableWorkloadBalancing: boolean;
+    enableExpertiseMatching: boolean;
+    maxTasksPerAgent: number;
+    agentOverloadThreshold: number;
+    taskTimeoutMinutes: number;
+    enableLlmAssignment: boolean;
+    llmConfidenceThreshold: number;
+    fallbackStrategy: AssignmentStrategy;
+    enableTaskDependencies: boolean;
+    enableLateJoinHandling: boolean;
+    preventSimultaneousStart: boolean;
+}
+/**
+ * Task event types for EventBus integration
+ */
+export type TaskEventType = 'task_created' | 'task_assigned' | 'task_started' | 'task_progress_updated' | 'task_completed' | 'task_failed' | 'task_cancelled' | 'task_reassigned' | 'agent_overloaded' | 'channel_workload_analyzed';
+/**
+ * Task event data
+ */
+export interface TaskEventData {
+    task: ChannelTask;
+    previousStatus?: TaskStatus;
+    assignmentAnalysis?: AgentAssignmentAnalysis;
+    workloadAnalysis?: ChannelWorkloadAnalysis;
+    trigger: 'manual' | 'automatic' | 'system';
+    timestamp: number;
+}
+//# sourceMappingURL=TaskTypes.d.ts.map

package/dist/types/TaskTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskTypes.d.ts","sourceRoot":"","sources":["../../src/types/TaskTypes.ts"],"names":[],"mappings":"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"}

package/dist/types/TaskTypes.js

@@ -0,0 +1,21 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+export {};
+//# sourceMappingURL=TaskTypes.js.map

package/dist/types/TaskTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskTypes.js","sourceRoot":"","sources":["../../src/types/TaskTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/types/TensorFlowTypes.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * TensorFlow.js Integration Types
+ *
+ * Type definitions for MXF's TensorFlow.js integration layer.
+ * Covers model management, training configuration, inference results,
+ * and tensor memory monitoring.
+ *
+ * Feature flag: TENSORFLOW_ENABLED (default: false)
+ *
+ * Design notes:
+ * - All model types supported: dense classifiers, autoencoders, LSTMs, DQNs,
+ *   regression, embeddings, and TransE knowledge graph embeddings
+ * - Models persist to MongoDB GridFS (default) or local filesystem
+ * - Inference returns plain number[] via InferenceResult — consumers never touch tensors
+ * - Training supports both standard supervised (train) and custom loops (trainCustom)
+ *   for contrastive loss, experience replay, and margin-based ranking
+ * - Using pure JS backend (@tensorflow/tfjs) for Bun compatibility.
+ *   Native backend (@tensorflow/tfjs-node) can be added later for 10-50x speedup
+ *   if Node.js is used.
+ */
+/**
+ * Model architecture types supported by MxfMLService
+ */
+export declare enum MxfModelType {
+    /** Standard feedforward classifier with Dense layers and sigmoid/softmax output */
+    DENSE_CLASSIFIER = "dense_classifier",
+    /** Encoder-decoder architecture for anomaly detection via reconstruction error */
+    AUTOENCODER = "autoencoder",
+    /** Long Short-Term Memory network for time series forecasting */
+    LSTM = "lstm",
+    /** Deep Q-Network for reinforcement learning Q-value approximation */
+    DQN = "dqn",
+    /** Standard regression with linear output */
+    REGRESSION = "regression",
+    /** Embedding model for learned vector representations (e.g., surprise embedder) */
+    EMBEDDING = "embedding",
+    /** TransE knowledge graph embedding model with margin-based ranking loss */
+    TRANSE = "transe"
+}
+/**
+ * Model lifecycle status
+ */
+export declare enum ModelStatus {
+    /** Model is registered but has no trained weights */
+    UNTRAINED = "untrained",
+    /** Model is currently being trained */
+    TRAINING = "training",
+    /** Model has trained weights and is ready for inference */
+    TRAINED = "trained",
+    /** Training failed — model may have partial weights or none */
+    FAILED = "failed"
+}
+/**
+ * Backend for model persistence
+ */
+export declare enum ModelStorageBackend {
+    /** Local filesystem storage (for development) */
+    FILESYSTEM = "filesystem",
+    /** MongoDB GridFS storage (production default) */
+    MONGODB_GRIDFS = "mongodb_gridfs"
+}
+/**
+ * Configuration for a registered model
+ *
+ * Each model that MxfMLService manages has one of these configs.
+ * The config is provided at registration time by the consuming service.
+ */
+export interface MxfModelConfig {
+    /** Unique identifier for this model (e.g., 'error_prediction', 'anomaly_autoencoder') */
+    modelId: string;
+    /** Architecture type — determines how the model is built, trained, and used */
+    type: MxfModelType;
+    /** Expected input tensor shape (excluding batch dimension) */
+    inputShape: number[];
+    /** Expected output tensor shape (excluding batch dimension) */
+    outputShape: number[];
+    /** Minimum training samples required before first training */
+    minTrainingSamples: number;
+    /** Training batch size */
+    batchSize: number;
+    /** Training epochs per training run */
+    epochs: number;
+    /** Fraction of training data used for validation (0-1) */
+    validationSplit: number;
+    /** Optimizer learning rate */
+    learningRate: number;
+    /** Whether to auto-train when sufficient data is available */
+    autoTrain: boolean;
+    /** Interval between automatic retraining runs in milliseconds */
+    retrainIntervalMs: number;
+    /** Model-specific hyperparameters (e.g., DQN replay buffer size, TransE margin) */
+    hyperparameters?: Record<string, number | string | boolean>;
+}
+/**
+ * Runtime state for a managed model
+ *
+ * Tracks the TF.js model instance, training metrics, and usage statistics.
+ * The `model` field holds the actual tf.LayersModel at runtime.
+ */
+export interface MxfModel {
+    /** Registration configuration */
+    config: MxfModelConfig;
+    /** Current lifecycle status */
+    status: ModelStatus;
+    /**
+     * The TF.js model instance.
+     * Typed as `unknown` to avoid importing @tensorflow/tfjs at type level.
+     * At runtime this is a tf.LayersModel (or tf.Sequential).
+     */
+    model: unknown;
+    /** Metrics from the most recent training run */
+    lastTrainingMetrics?: TrainingMetrics;
+    /** Unix timestamp of last successful training */
+    lastTrainedAt?: number;
+    /** Number of predictions made since last training */
+    predictionsSinceTraining: number;
+    /** Total number of training samples used across all training runs */
+    totalTrainingSamples: number;
+}
+/**
+ * Training run metrics
+ *
+ * Returned by both train() and trainCustom() methods.
+ */
+export interface TrainingMetrics {
+    /** Final training loss */
+    loss: number;
+    /** Final validation loss (if validationSplit > 0) */
+    valLoss?: number;
+    /** Final training accuracy (for classifiers) */
+    accuracy?: number;
+    /** Final validation accuracy (for classifiers) */
+    valAccuracy?: number;
+    /** Number of epochs completed (may be less than config.epochs if early-stopped) */
+    epochsCompleted: number;
+    /** Wall-clock training duration in milliseconds */
+    durationMs: number;
+    /** Number of training samples used in this run */
+    samplesUsed: number;
+}
+/**
+ * Inference result returned by predict() and predictBatch()
+ *
+ * Contains plain number[] values — all tensor operations are encapsulated
+ * inside MxfMLService. Consumer services never touch tensors.
+ */
+export interface InferenceResult {
+    /** Output values as plain numbers */
+    values: number[];
+    /** Model that produced this result */
+    modelId: string;
+    /** Whether result came from the ML model or a heuristic fallback */
+    source: 'model' | 'heuristic';
+    /** Inference latency in milliseconds */
+    latencyMs: number;
+}
+/**
+ * Reconstruction result for autoencoder models
+ *
+ * Returned by predictWithReconstruction() for anomaly detection.
+ * Includes the reconstructed output and the reconstruction error.
+ */
+export interface ReconstructionResult {
+    /** Reconstructed output values */
+    reconstruction: number[];
+    /** Per-feature reconstruction error (input - reconstruction)^2 */
+    featureErrors: number[];
+    /** Mean squared reconstruction error (anomaly score) */
+    reconstructionError: number;
+    /** Model that produced this result */
+    modelId: string;
+    /** Whether result came from the ML model or a heuristic fallback */
+    source: 'model' | 'heuristic';
+    /** Inference latency in milliseconds */
+    latencyMs: number;
+}
+/**
+ * Tensor memory usage snapshot
+ *
+ * Wraps tf.memory() output with a timestamp for monitoring.
+ */
+export interface TensorMemoryStats {
+    /** Number of tensors currently allocated */
+    numTensors: number;
+    /** Number of unique data buffers (shared tensors share buffers) */
+    numDataBuffers: number;
+    /** Total bytes used by tensors */
+    numBytes: number;
+    /** Unix timestamp when stats were collected */
+    timestamp: number;
+}
+/**
+ * TensorFlow.js configuration
+ *
+ * Controls feature flag, storage backend, memory monitoring,
+ * and auto-training behavior.
+ */
+export interface TensorFlowConfig {
+    /** Master enable flag (default: false, opt-in) */
+    enabled: boolean;
+    /** Where to persist trained models */
+    storageBackend: ModelStorageBackend;
+    /** Filesystem path for model storage (only used when backend is FILESYSTEM) */
+    modelStoragePath: string;
+    /** Interval for tf.memory() logging in milliseconds (0 to disable) */
+    memoryLoggingIntervalMs: number;
+    /** Memory warning threshold in bytes */
+    maxTensorMemoryBytes: number;
+    /** Enable verbose TF.js debug logging */
+    debug: boolean;
+    /** Whether auto-training is enabled globally */
+    autoTrainEnabled: boolean;
+    /** Default retrain interval in milliseconds (models can override) */
+    globalRetrainIntervalMs: number;
+}
+/**
+ * Environment variable names for TensorFlow.js configuration
+ *
+ * All variables are optional — defaults are used when not set.
+ */
+export declare const TENSORFLOW_ENV_VARS: {
+    readonly ENABLED: "TENSORFLOW_ENABLED";
+    readonly STORAGE_BACKEND: "TENSORFLOW_STORAGE_BACKEND";
+    readonly MODEL_STORAGE_PATH: "TENSORFLOW_MODEL_STORAGE_PATH";
+    readonly MEMORY_LOGGING_INTERVAL_MS: "TENSORFLOW_MEMORY_LOGGING_INTERVAL_MS";
+    readonly MAX_TENSOR_MEMORY_BYTES: "TENSORFLOW_MAX_TENSOR_MEMORY_BYTES";
+    readonly DEBUG: "TENSORFLOW_DEBUG";
+    readonly AUTO_TRAIN_ENABLED: "TENSORFLOW_AUTO_TRAIN_ENABLED";
+    readonly GLOBAL_RETRAIN_INTERVAL_MS: "TENSORFLOW_GLOBAL_RETRAIN_INTERVAL_MS";
+};
+/**
+ * Default configuration values
+ *
+ * Feature is disabled by default (opt-in via TENSORFLOW_ENABLED=true).
+ * GridFS is the default storage backend for production use.
+ */
+export declare const DEFAULT_TENSORFLOW_CONFIG: TensorFlowConfig;
+//# sourceMappingURL=TensorFlowTypes.d.ts.map

package/dist/types/TensorFlowTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TensorFlowTypes.d.ts","sourceRoot":"","sources":["../../src/types/TensorFlowTypes.ts"],"names":[],"mappings":"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"}

package/dist/types/TensorFlowTypes.js

@@ -0,0 +1,115 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * TensorFlow.js Integration Types
+ *
+ * Type definitions for MXF's TensorFlow.js integration layer.
+ * Covers model management, training configuration, inference results,
+ * and tensor memory monitoring.
+ *
+ * Feature flag: TENSORFLOW_ENABLED (default: false)
+ *
+ * Design notes:
+ * - All model types supported: dense classifiers, autoencoders, LSTMs, DQNs,
+ *   regression, embeddings, and TransE knowledge graph embeddings
+ * - Models persist to MongoDB GridFS (default) or local filesystem
+ * - Inference returns plain number[] via InferenceResult — consumers never touch tensors
+ * - Training supports both standard supervised (train) and custom loops (trainCustom)
+ *   for contrastive loss, experience replay, and margin-based ranking
+ * - Using pure JS backend (@tensorflow/tfjs) for Bun compatibility.
+ *   Native backend (@tensorflow/tfjs-node) can be added later for 10-50x speedup
+ *   if Node.js is used.
+ */
+/**
+ * Model architecture types supported by MxfMLService
+ */
+export var MxfModelType;
+(function (MxfModelType) {
+    /** Standard feedforward classifier with Dense layers and sigmoid/softmax output */
+    MxfModelType["DENSE_CLASSIFIER"] = "dense_classifier";
+    /** Encoder-decoder architecture for anomaly detection via reconstruction error */
+    MxfModelType["AUTOENCODER"] = "autoencoder";
+    /** Long Short-Term Memory network for time series forecasting */
+    MxfModelType["LSTM"] = "lstm";
+    /** Deep Q-Network for reinforcement learning Q-value approximation */
+    MxfModelType["DQN"] = "dqn";
+    /** Standard regression with linear output */
+    MxfModelType["REGRESSION"] = "regression";
+    /** Embedding model for learned vector representations (e.g., surprise embedder) */
+    MxfModelType["EMBEDDING"] = "embedding";
+    /** TransE knowledge graph embedding model with margin-based ranking loss */
+    MxfModelType["TRANSE"] = "transe";
+})(MxfModelType || (MxfModelType = {}));
+/**
+ * Model lifecycle status
+ */
+export var ModelStatus;
+(function (ModelStatus) {
+    /** Model is registered but has no trained weights */
+    ModelStatus["UNTRAINED"] = "untrained";
+    /** Model is currently being trained */
+    ModelStatus["TRAINING"] = "training";
+    /** Model has trained weights and is ready for inference */
+    ModelStatus["TRAINED"] = "trained";
+    /** Training failed — model may have partial weights or none */
+    ModelStatus["FAILED"] = "failed";
+})(ModelStatus || (ModelStatus = {}));
+/**
+ * Backend for model persistence
+ */
+export var ModelStorageBackend;
+(function (ModelStorageBackend) {
+    /** Local filesystem storage (for development) */
+    ModelStorageBackend["FILESYSTEM"] = "filesystem";
+    /** MongoDB GridFS storage (production default) */
+    ModelStorageBackend["MONGODB_GRIDFS"] = "mongodb_gridfs";
+})(ModelStorageBackend || (ModelStorageBackend = {}));
+/**
+ * Environment variable names for TensorFlow.js configuration
+ *
+ * All variables are optional — defaults are used when not set.
+ */
+export const TENSORFLOW_ENV_VARS = {
+    ENABLED: 'TENSORFLOW_ENABLED',
+    STORAGE_BACKEND: 'TENSORFLOW_STORAGE_BACKEND',
+    MODEL_STORAGE_PATH: 'TENSORFLOW_MODEL_STORAGE_PATH',
+    MEMORY_LOGGING_INTERVAL_MS: 'TENSORFLOW_MEMORY_LOGGING_INTERVAL_MS',
+    MAX_TENSOR_MEMORY_BYTES: 'TENSORFLOW_MAX_TENSOR_MEMORY_BYTES',
+    DEBUG: 'TENSORFLOW_DEBUG',
+    AUTO_TRAIN_ENABLED: 'TENSORFLOW_AUTO_TRAIN_ENABLED',
+    GLOBAL_RETRAIN_INTERVAL_MS: 'TENSORFLOW_GLOBAL_RETRAIN_INTERVAL_MS',
+};
+/**
+ * Default configuration values
+ *
+ * Feature is disabled by default (opt-in via TENSORFLOW_ENABLED=true).
+ * GridFS is the default storage backend for production use.
+ */
+export const DEFAULT_TENSORFLOW_CONFIG = {
+    enabled: false,
+    storageBackend: ModelStorageBackend.MONGODB_GRIDFS,
+    modelStoragePath: 'data/tensorflow/models',
+    memoryLoggingIntervalMs: 60_000, // 1 minute
+    maxTensorMemoryBytes: 536_870_912, // 512 MB
+    debug: false,
+    autoTrainEnabled: true,
+    globalRetrainIntervalMs: 3_600_000, // 1 hour
+};
+//# sourceMappingURL=TensorFlowTypes.js.map

package/dist/types/TensorFlowTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TensorFlowTypes.js","sourceRoot":"","sources":["../../src/types/TensorFlowTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;GAEG;AACH,MAAM,CAAN,IAAY,YAqBX;AArBD,WAAY,YAAY;IACpB,mFAAmF;IACnF,qDAAqC,CAAA;IAErC,kFAAkF;IAClF,2CAA2B,CAAA;IAE3B,iEAAiE;IACjE,6BAAa,CAAA;IAEb,sEAAsE;IACtE,2BAAW,CAAA;IAEX,6CAA6C;IAC7C,yCAAyB,CAAA;IAEzB,mFAAmF;IACnF,uCAAuB,CAAA;IAEvB,4EAA4E;IAC5E,iCAAiB,CAAA;AACrB,CAAC,EArBW,YAAY,KAAZ,YAAY,QAqBvB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,WAYX;AAZD,WAAY,WAAW;IACnB,qDAAqD;IACrD,sCAAuB,CAAA;IAEvB,uCAAuC;IACvC,oCAAqB,CAAA;IAErB,2DAA2D;IAC3D,kCAAmB,CAAA;IAEnB,+DAA+D;IAC/D,gCAAiB,CAAA;AACrB,CAAC,EAZW,WAAW,KAAX,WAAW,QAYtB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,mBAMX;AAND,WAAY,mBAAmB;IAC3B,iDAAiD;IACjD,gDAAyB,CAAA;IAEzB,kDAAkD;IAClD,wDAAiC,CAAA;AACrC,CAAC,EANW,mBAAmB,KAAnB,mBAAmB,QAM9B;AA4MD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAC/B,OAAO,EAAE,oBAAoB;IAC7B,eAAe,EAAE,4BAA4B;IAC7C,kBAAkB,EAAE,+BAA+B;IACnD,0BAA0B,EAAE,uCAAuC;IACnE,uBAAuB,EAAE,oCAAoC;IAC7D,KAAK,EAAE,kBAAkB;IACzB,kBAAkB,EAAE,+BAA+B;IACnD,0BAA0B,EAAE,uCAAuC;CAC7D,CAAC;AAEX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAqB;IACvD,OAAO,EAAE,KAAK;IACd,cAAc,EAAE,mBAAmB,CAAC,cAAc;IAClD,gBAAgB,EAAE,wBAAwB;IAC1C,uBAAuB,EAAE,MAAM,EAAY,WAAW;IACtD,oBAAoB,EAAE,WAAW,EAAU,SAAS;IACpD,KAAK,EAAE,KAAK;IACZ,gBAAgB,EAAE,IAAI;IACtB,uBAAuB,EAAE,SAAS,EAAS,SAAS;CACvD,CAAC"}