@channela9/mogi 0.1.2

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to npm
+on:
+  release:
+    types: [published]
+  # Alternatively, trigger on a tag push:
+  # push:
+  #   tags:
+  #     - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Publish Package
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shaun Colegado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# Mogi
+
+Mogi is a simulation framework that allows you to create and run complex agent-based simulations using AI-driven nodes and processes. This README provides an overview of how to set up and use Mogi, including a detailed example of an amusement park simulation.
+
+## Installation
+
+To install Mogi, clone the repository and install the dependencies:
+
+```bash
+git clone https://github.com/yourusername/mogi.git
+cd mogi
+npm install
+```
+
+## Usage
+
+### Creating a Simulation
+
+To create a simulation, you need to initialize the `MogiSimulation` class with a configuration object. You can then add agents and define processes and nodes that the agents will go through.
+
+### Example: Amusement Park Simulation
+
+Below is an example of how to set up an amusement park simulation where agents (riders) go through ticketing, ride, and exit nodes.
+
+#### Step 1: Initialize AI Service
+
+```typescript
+import { GoogleAIService } from "./ai-interfaces/ai-google";
+
+const AI = new GoogleAIService("YOUR_API_KEY", "gemini-2.0-flash-exp");
+```
+
+#### Step 2: Create Simulation Instance
+
+```typescript
+import { MogiSimulation } from "./mogi";
+
+const simulation = new MogiSimulation({
+  description: "Amusement Park",
+  delayMs: 3000,
+  maxConcurrency: 2,
+  printLogs: true,
+});
+```
+
+#### Step 3: Add Agents
+
+```typescript
+const rider1Id = simulation.addAgent({
+  attributes: { name: "Jake", money: 10, happiness: 5, height: 140, fatigue: 0 },
+}, "Jake");
+
+const rider2Id = simulation.addAgent({
+  attributes: { name: "John", money: 10, happiness: 5, height: 180, fatigue: 0 },
+}, "John");
+```
+
+#### Step 4: Create Nodes
+
+```typescript
+import { createMogiNode } from "./mogi";
+import { SchemaType } from "@google/generative-ai";
+
+const ticketingNode = createMogiNode(
+  'ticketBox',
+  AI,
+  `
+  As ticketing staff:
+  - Verify rider height (150-200cm)
+  - Charge $2 if valid
+  - Update worker fatigue (+1)
+  - Update rider money and happiness
+`,
+  {
+    ticket: {
+      type: SchemaType.STRING,
+      enum: ["standard", "premium"],
+    },
+    money: {
+      type: SchemaType.NUMBER,
+    }
+  },
+  { useChainOfThought: true }
+);
+
+const rideNode = createMogiNode(
+  'rideOperator',
+  AI,
+  `
+  As ride operator:
+  - Simulate ride experience
+  - Increase rider happiness (1-5 points)
+  - Increase rider fatigue (1-3 points)
+`,
+  {
+    happiness: { type: SchemaType.NUMBER },
+    fatigue: { type: SchemaType.NUMBER },
+  },
+  { useChainOfThought: false }
+);
+
+const exitNode = createMogiNode(
+  'exitStaff',
+  AI,
+  `
+  As exit staff:
+  - Give farewell greeting
+  - Final happiness adjustment (±1)
+`,
+  {
+    happiness: { type: SchemaType.NUMBER },
+    fatigue: { type: SchemaType.NUMBER },
+  },
+  { useChainOfThought: false }
+);
+```
+
+#### Step 5: Create Processes
+
+```typescript
+import { MogiProcess } from "./mogi";
+
+const fullRideProcess = new MogiProcess("full-ride")
+  .addNode(ticketingNode)
+  .addNode(rideNode)
+  .addNode(exitNode);
+
+const shortProcess = new MogiProcess("short-exit").addNode(exitNode);
+```
+
+#### Step 6: Create Conditional Process
+
+```typescript
+import { MogiConditionalProcess } from "./mogi";
+
+const heightCondition = (min: number, max: number) => {
+  return (agent: MogiAgentState) => {
+    const height = agent.attributes.height;
+    if (height) return height >= min && height <= max;
+    return false;
+  };
+};
+
+const amusementParkFlow = new MogiConditionalProcess(
+  "height-check-flow",
+  heightCondition(150, 200),
+  fullRideProcess,
+  shortProcess
+);
+```
+
+#### Step 7: Run Simulation
+
+```typescript
+simulation.runProcess(amusementParkFlow).then(() => {
+  console.log("Simulation completed\n");
+
+  // Helper to display agent history
+  const logHistory = (agentId: string) => {
+    const agent = simulation.getAgentState(agentId);
+    console.log(`\n${agent.attributes.name}'s journey:`);
+    agent.history.forEach((entry) => {
+      console.log(`[${entry.timestamp.toLocaleTimeString()}] ${JSON.stringify(entry.changes)}`);
+    });
+    console.log(agent.attributes);
+  };
+
+  logHistory(rider1Id);
+  logHistory(rider2Id);
+
+  const usage = simulation.getAIUsage();
+  console.log(`API Usage:
+    Calls: ${usage.totalCalls}
+    Input tokens: ${usage.totalInputTokens}
+    Output tokens: ${usage.totalOutputTokens}
+    Estimated cost: $${usage.estimatedCost.toFixed(4)}`);
+});
+```
+
+## License
+
+This project is licensed under the MIT License.

package/ai-interface.d.ts

@@ -0,0 +1,96 @@
+import { Schema } from "@google/generative-ai";
+
+export type AIPromptResponse = string | string[];
+export type TokenUsage = { input: number; output: number };
+
+export interface AIUsageStats {
+  totalCalls: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  estimatedCost: number;
+}
+
+export type AIInterfaceModelsDefinition = {
+  primary: string;
+  utility: string;
+};
+
+/**
+ * Abstract class representing an AI service.
+ * All AI services should implement as singletons.
+ */
+export abstract class AIService {
+  protected abstract usageStats: AIUsageStats;
+  static instance: AIService;
+  /**
+   * Creates a schema from an object.
+   * @param object - The object to create a schema from.
+   * @returns The created schema.
+   */
+  abstract createSchema(object: object): Schema;
+  /**
+   * Prompts the AI service with a system message, content, and instruction.
+   * @param system - The system message.
+   * @param content - The content to process.
+   * @param instruction - The instruction for the AI.
+   * @param schema - The schema for the response.
+   * @returns The AI prompt response.
+   */
+  abstract prompt(
+    system: string,
+    content: string,
+    instruction: string,
+    schema?: Schema
+  ): Promise<AIPromptResponse>;
+  /**
+   * Prompts the AI service with a system message, content, and instruction, and generates reasoning.
+   * @param system - The system message.
+   * @param content - The content to process.
+   * @param instruction - The instruction for the AI.
+   * @param schema - The schema for the response.
+   * @returns The AI prompt response with reasoning.
+   */
+  abstract promptThinking(
+    system: string,
+    content: string,
+    instruction: string,
+    schema?: Schema
+  ): Promise<AIPromptResponse>;
+  /**
+   * Sets the primary model for the AI service.
+   * @param model - The primary model.
+   */
+  abstract setPrimaryModel(model: string): void;
+  /**
+   * Sets the utility model for the AI service.
+   * @param model - The utility model.
+   */
+  abstract setUtilityModel(model: string): void;
+  /**
+   * Sets the generation configuration for the AI service.
+   * @param config - The generation configuration.
+   */
+  abstract setGenerationConfig(config: object): void;
+  /**
+   * Calculates the cost of the AI service based on input and output tokens.
+   * @param inputTokens - The number of input tokens.
+   * @param outputTokens - The number of output tokens.
+   * @returns The calculated cost.
+   */
+  abstract calculateCost(inputTokens: number, outputTokens: number): number;
+  /**
+   * Sets the pricing for the AI service.
+   * @param input - The cost per million input tokens.
+   * @param output - The cost per million output tokens.
+   */
+  abstract setPricing(input: number, output: number): void;
+  /**
+   * Gets the usage statistics for the AI service.
+   * @returns The usage statistics.
+   */
+  getUsageStats(): AIUsageStats;
+  /**
+   * Resets the usage statistics for the AI service.
+   */
+  resetUsageStats(): void;
+}

package/ai-interface.ts

@@ -0,0 +1,53 @@
+// ai.ts - Universal AI Interface
+import { SchemaType, Schema } from "@google/generative-ai";
+
+export type AIPromptResponse = string | string[];
+export type TokenUsage = { input: number; output: number };
+
+export interface AIUsageStats {
+  totalCalls: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  estimatedCost: number;
+}
+
+export type AIInterfaceModelsDefinition = {
+  primary: string;
+  utility: string;
+};
+
+// all AI services should implement as singletons
+export abstract class AIService {
+  protected abstract usageStats: AIUsageStats;
+  static instance: AIService;
+  abstract createSchema(object: object): Schema;
+  abstract prompt(
+    system: string,
+    content: string,
+    instruction: string,
+    schema?: Schema
+  ): Promise<AIPromptResponse>;
+  abstract promptThinking(
+    system: string,
+    content: string,
+    instruction: string,
+    schema?: Schema
+  ): Promise<AIPromptResponse>;
+  abstract setPrimaryModel(model: string): void;
+  abstract setUtilityModel(model: string): void;
+  abstract setGenerationConfig(config: object): void;
+  abstract calculateCost(inputTokens: number, outputTokens: number): number
+  abstract setPricing(input: number, output: number): void;
+  getUsageStats(): AIUsageStats {
+    return this.usageStats;
+  }
+
+  resetUsageStats(): void {
+    this.usageStats = {
+      totalCalls: 0,
+      totalInputTokens: 0,
+      totalOutputTokens: 0,
+      estimatedCost: 0,
+    };
+  }
+}

package/ai-models/ai-google.ts

@@ -0,0 +1,214 @@
+// ai/gemini.ts
+import {
+  GoogleGenerativeAI,
+  HarmCategory,
+  HarmBlockThreshold,
+  type GenerationConfig,
+  type SafetySetting,
+  type Schema,
+  SchemaType,
+  GenerateContentResponse,
+} from "@google/generative-ai";
+import { AIService, AIPromptResponse } from "../ai-interface";
+
+const SAFETY_SETTINGS: SafetySetting[] = [
+  {
+    category: HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
+    threshold: HarmBlockThreshold.BLOCK_NONE,
+  },
+  {
+    category: HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+    threshold: HarmBlockThreshold.BLOCK_NONE,
+  },
+  {
+    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
+    threshold: HarmBlockThreshold.BLOCK_NONE,
+  },
+  {
+    category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+    threshold: HarmBlockThreshold.BLOCK_NONE,
+  },
+];
+
+const DEFAULT_CONFIG: GenerationConfig = {
+  temperature: 0.1,
+  topP: 1,
+  topK: 1,
+  frequencyPenalty: 0.5,
+};
+
+export class GoogleAIService extends AIService {
+  static instance: GoogleAIService;
+
+  protected usageStats =  {
+    totalCalls: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    estimatedCost: 0,
+  };
+
+  private genAI: GoogleGenerativeAI;
+  private models = {
+    primary: "gemini-1.5-flash",
+    utility: "gemini-1.5-flash",
+  };
+  private config: GenerationConfig = DEFAULT_CONFIG;
+  private modelPricing = {
+    inputCostPerMToken: 0.15,
+    outputCostPerMToken: 0.60, // pessimistic pricing calculation. highest pricing bracket for Gemini 1.5 Pro >128k token prompts
+  };
+
+  constructor(apiKey: string, model: string, subModel?: string) {
+    super();
+
+    if (GoogleAIService.instance) {
+      return GoogleAIService.instance;
+    }
+
+    this.genAI = new GoogleGenerativeAI(apiKey);
+
+    this.models.primary = model;
+    if (subModel) {
+      this.models.utility = subModel;
+    } else {
+      this.models.utility = model;
+    }
+
+    GoogleAIService.instance = this;
+  }
+
+  createSchema(obj: object): Schema {
+    const properties: Record<string, Schema> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      properties[key] = this.inferSchema(value);
+    }
+    return { type: SchemaType.OBJECT, properties, nullable: false };
+  }
+
+  private inferSchema(value: unknown): Schema {
+    switch (typeof value) {
+      case "string":
+        return { type: SchemaType.STRING };
+      case "number":
+        return { type: SchemaType.NUMBER };
+      case "boolean":
+        return { type: SchemaType.BOOLEAN };
+      case "object":
+        if (Array.isArray(value)) {
+          return {
+            type: SchemaType.ARRAY,
+            items: value.length > 0 ? this.inferSchema(value[0]) : { type: SchemaType.STRING },
+          };
+        }
+        return value ? this.createSchema(value) : { type: SchemaType.OBJECT };
+      default:
+        return { type: SchemaType.STRING };
+    }
+  }
+
+  async prompt(
+    system: string,
+    content: string,
+    instruction: string,
+    schema?: Schema
+  ): Promise<AIPromptResponse> {
+    const model = this.genAI.getGenerativeModel({
+      model: this.models.primary,
+      generationConfig: DEFAULT_CONFIG,
+      safetySettings: SAFETY_SETTINGS,
+    });
+
+    try {
+      const result = await model.generateContent({
+        contents: [
+          { role: "model", parts: [{ text: system }] },
+          { role: "user", parts: [{ text: content }] },
+          { role: "user", parts: [{ text: instruction }] },
+        ],
+        // systemInstruction: "Respond with valid JSON only",
+        generationConfig: {
+          responseMimeType: "application/json",
+          responseSchema: schema,
+        },
+      });
+
+      this.updateUsage(result.response);
+
+      return result.response.text();
+    } catch (error) {
+      console.error("Gemini prompt error:", error);
+      return JSON.stringify({ error: "AI processing failed" });
+    }
+  }
+
+  async promptThinking(
+    system: string,
+    content: string,
+    instruction: string,
+    schema?: Schema
+  ): Promise<AIPromptResponse> {
+    const result = await this.prompt(system, content, instruction, schema);
+    const reasoning = await this.generateReasoning(system, `You added: ${result} to ${content}`);
+
+    console.log(result, reasoning);
+    return Array.isArray(result) ? [...result, reasoning] : [result, reasoning];
+  }
+
+  private async generateReasoning(system: string, content: string): Promise<string> {
+    const model = this.genAI.getGenerativeModel({
+      model: this.models.utility,
+      generationConfig: { ...DEFAULT_CONFIG, ...this.config, maxOutputTokens: 60 },
+      safetySettings: SAFETY_SETTINGS,
+    });
+
+    const result = await model.generateContent([
+      `ROLE: ${system}\n\n ${content}`,
+      "In natural language and in character, generate a very short statement that contextualizes the change made.",
+    ]);
+
+    this.updateUsage(result.response);
+
+    return result.response.text();
+  }
+
+  setPrimaryModel(model: string): void {
+    this.models.primary = model;
+  }
+  setUtilityModel(model: string): void {
+    this.models.utility = model;
+  }
+  setGenerationConfig(config: object): void {
+    this.config = config;
+  }
+
+  // API Usage Tracking
+  setPricing(input: number, output: number): void {
+    this.modelPricing = {
+      inputCostPerMToken: input,
+      outputCostPerMToken: output,
+    };
+  }
+
+  private updateUsage(response: GenerateContentResponse): void {
+    const usage = response.usageMetadata || {
+      promptTokenCount: 0,
+      candidatesTokenCount: 0,
+    };
+
+    this.usageStats.totalCalls++;
+    this.usageStats.totalInputTokens += usage.promptTokenCount;
+    this.usageStats.totalOutputTokens += usage.candidatesTokenCount;
+
+    this.usageStats.estimatedCost += this.calculateCost(
+      usage.promptTokenCount,
+      usage.candidatesTokenCount
+    );
+  }
+
+  calculateCost(inputTokens: number, outputTokens: number): number {
+    return (
+      (inputTokens / 1_000_000) * this.modelPricing.inputCostPerMToken +
+      (outputTokens / 1_000_000) * this.modelPricing.outputCostPerMToken
+    );
+  }
+}

package/mogi.d.ts

@@ -0,0 +1,225 @@
+import { Schema } from "@google/generative-ai";
+import { AIService, AIPromptResponse } from "./ai-interface";
+import { AIUsageStats } from "./ai-interface";
+
+declare type MogiAgentID = string;
+declare type MogiProcessID = string;
+declare type MogiNodeID = string;
+
+export interface MogiAgentState {
+  id: MogiAgentID;
+  attributes: Record<string, any>;
+  history: MogiAgentHistory[];
+}
+
+export interface MogiAgentHistory {
+  timestamp: Date;
+  processId?: MogiProcessID;
+  nodeId?: MogiNodeID;
+  changes: Record<string, any>;
+  reasoning?: string;
+}
+
+export interface MogiSimulationConfig {
+  id: string;
+  description: string;
+  delayMs: number;
+  maxConcurrency: number;
+  printLogs: boolean;
+}
+
+export interface MogiSimulationState {
+  currentProcessId: MogiProcessID | null;
+  activeAgents: MogiAgentID[];
+  nodeIndex: number;
+  isComplete: boolean;
+}
+
+export interface MogiProcessConfig {
+  retries: number;
+  timeoutMs: number;
+}
+
+export interface MogiNodeConfig {
+  aiService: AIService;
+  instructions: string;
+  appendMessage?: string;
+  schema?: Schema;
+  useChainOfThought: boolean;
+}
+
+/**
+ * Class representing the Mogi simulation.
+ */
+export class MogiSimulation {
+  constructor(config?: Partial<MogiSimulationConfig>);
+  /**
+   * Adds an agent to the simulation.
+   * @param initialState - The initial state of the agent.
+   * @returns The ID of the added agent.
+   */
+  addAgent(initialState: Omit<MogiAgentState, "id" | "history">): MogiAgentID;
+  /**
+   * Gets the state of an agent by ID.
+   * @param id - The ID of the agent.
+   * @returns The state of the agent.
+   */
+  getAgentState(id: MogiAgentID): MogiAgentState;
+  /**
+   * Gets the state of all agents in the simulation.
+   * @returns An array of agent states.
+   */
+  getAllAgents(): MogiAgentState[];
+  /**
+   * Gets the current state of the simulation.
+   * @returns The state of the simulation.
+   */
+  getSimulationState(): MogiSimulationState;
+  /**
+   * Initializes a process in the simulation.
+   * @param process - The process to initialize.
+   */
+  initializeProcess(process: MogiProcess): Promise<void>;
+  /**
+   * Executes a single step of the simulation.
+   * @returns A promise that resolves to a boolean indicating if there are more steps to execute.
+   */
+  executeStep(): Promise<boolean>;
+  /**
+   * Runs a process in the simulation.
+   * @param process - The process to run.
+   */
+  runProcess(process: MogiProcess): Promise<void>;
+  /**
+   * Tracks an AI service for usage statistics.
+   * @param service - The AI service to track.
+   */
+  private trackAIService(service: AIService): void;
+  /**
+   * Gets the usage statistics for all tracked AI services.
+   * @returns The usage statistics.
+   */
+  getAIUsage(): AIUsageStats;
+  /**
+   * Resets the usage statistics for all tracked AI services.
+   */
+  resetAIUsage(): void;
+}
+
+/**
+ * Class representing a process in the Mogi simulation.
+ */
+export class MogiProcess {
+  constructor(id: MogiProcessID, config?: MogiProcessConfig);
+  /**
+   * Adds a node to the process.
+   * @param node - The node to add.
+   * @returns The process instance.
+   */
+  addNode(node: MogiNode): this;
+  /**
+   * Executes the process for a set of agents.
+   * @param agents - The agents to process.
+   * @param simConfig - The simulation configuration.
+   */
+  execute(agents: MogiAgentState[], simConfig: MogiSimulationConfig): Promise<void>;
+  /**
+   * Resets the execution state of the process.
+   */
+  resetExecution(): void;
+  /**
+   * Executes a single step for an agent in the process.
+   * @param agent - The agent to process.
+   * @param simConfig - The simulation configuration.
+   * @returns A promise that resolves to a boolean indicating if there are more steps to execute.
+   */
+  executeAgentStep(agent: MogiAgentState, simConfig: MogiSimulationConfig): Promise<boolean>;
+  /**
+   * Gets the AI services used by the process.
+   * @returns An array of AI services.
+   */
+  getAIServices(): AIService[];
+}
+
+/**
+ * Class representing a node in the Mogi simulation.
+ */
+export class MogiNode {
+  constructor(
+    id: MogiNodeID,
+    config: MogiNodeConfig
+  );
+  /**
+   * Executes the node for an agent.
+   * @param agent - The agent to process.
+   * @param delayMs - The delay in milliseconds before processing.
+   */
+  execute(agent: MogiAgentState, delayMs: number): Promise<void>;
+  /**
+   * Gets the AI service used by the node.
+   * @returns The AI service.
+   */
+  getAIService(): AIService;
+}
+
+/**
+ * Creates a Mogi node with AI-driven instructions.
+ * @param ai - The AI service to use.
+ * @param instructions - The instructions for the node.
+ * @param schema - The schema for the node.
+ * @returns The created Mogi node.
+ */
+export function createMogiNode(
+  ai: AIService,
+  instructions: string,
+  schema?: Schema
+): MogiNode;
+
+/**
+ * Utility function to encapsulate schemas.
+ * @param schemas - The schemas to encapsulate.
+ * @returns The encapsulated schema.
+ */
+export function encapsulateSchema(schemas: { [k: string]: Schema }): Schema;
+
+/**
+ * Class representing a conditional process in the Mogi simulation.
+ */
+export class MogiConditionalProcess extends MogiProcess {
+  constructor(
+    id: string,
+    condition: (agent: MogiAgentState) => boolean,
+    trueBranch: MogiProcess,
+    falseBranch: MogiProcess,
+    nodes?: MogiNode[],
+    config?: MogiProcessConfig
+  );
+  /**
+   * Executes a conditional step for a set of agents.
+   * @param agents - The agents to process.
+   * @param simConfig - The simulation configuration.
+   * @returns A promise that resolves to a boolean indicating if there are more steps to execute.
+   */
+  executeConditionalStep(agents: MogiAgentState[], simConfig: MogiSimulationConfig): Promise<boolean>;
+  /**
+   * Resets the execution state of the conditional process.
+   */
+  resetExecution(): void;
+  /**
+   * Updates the branches of the conditional process.
+   * @param trueBranch - The new true branch process.
+   * @param falseBranch - The new false branch process.
+   */
+  updateBranches(trueBranch?: MogiProcess, falseBranch?: MogiProcess): void;
+  /**
+   * Gets the active branch for an agent.
+   * @param agentId - The ID of the agent.
+   * @returns The active branch process.
+   */
+  getActiveBranch(agentId: MogiAgentID): MogiProcess | null;
+  /**
+   * Gets the AI services used by the conditional process.
+   * @returns An array of AI services.
+   */
+  getAIServices(): AIService[];
+}

package/mogi.ts

@@ -0,0 +1,447 @@
+// mogi.ts
+import { AIService, AIUsageStats, type AIPromptResponse } from "./ai-interface";
+import { Schema, SchemaType } from "@google/generative-ai";
+
+type MogiAgentID = string;
+type MogiProcessID = string;
+type MogiNodeID = string;
+
+export interface MogiAgentState {
+  id: MogiAgentID;
+  attributes: Record<string, any>;
+  history: MogiAgentHistory[];
+}
+
+export interface MogiAgentHistory {
+  timestamp: Date;
+  processId?: MogiProcessID;
+  nodeId?: MogiNodeID;
+  changes: Record<string, any>;
+  reasoning?: string;
+}
+
+export interface MogiSimulationConfig {
+  id: string;
+  description: string;
+  delayMs: number;
+  maxConcurrency: number;
+  printLogs: boolean;
+}
+
+export interface MogiSimulationState {
+  currentProcessId: MogiProcessID | null;
+  activeAgents: MogiAgentID[];
+  nodeIndex: number;
+  isComplete: boolean;
+}
+
+export interface MogiProcessConfig {
+  retries: number;
+  timeoutMs: number;
+}
+
+export interface MogiNodeConfig {
+  aiService: AIService;
+  instructions: string;
+  appendMessage?: string;
+  schema?: Schema;
+  useChainOfThought: boolean;
+}
+
+export class MogiSimulation {
+  private aiServices: Set<AIService> = new Set();
+  private globalUsage: AIUsageStats = {
+    totalCalls: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    estimatedCost: 0,
+  };
+
+  private executionQueue: Array<{
+    processId: MogiProcessID;
+    agentId: MogiAgentID;
+    nodeIndex: number;
+  }> = [];
+  private currentState: MogiSimulationState = {
+    currentProcessId: null,
+    activeAgents: [],
+    nodeIndex: 0,
+    isComplete: true,
+  };
+
+  private agents: Map<MogiAgentID, MogiAgentState> = new Map();
+  private processes: MogiProcess[] = [];
+  private config: MogiSimulationConfig;
+
+  constructor(config: Partial<MogiSimulationConfig> = {}) {
+    this.config = {
+      id: crypto.randomUUID(),
+      description: "Unnamed Simulation",
+      delayMs: 1500,
+      maxConcurrency: 5,
+      printLogs: false,
+      ...config,
+    };
+  }
+
+  addAgent(
+    initialState: Omit<MogiAgentState, "id" | "history">,
+    id: string = crypto.randomUUID()
+  ): MogiAgentID {
+    this.agents.set(id, {
+      id,
+      attributes: initialState.attributes,
+      history: [],
+    });
+    return id;
+  }
+
+  public getAgentState(id: MogiAgentID): MogiAgentState {
+    const agent = this.agents.get(id);
+    if (!agent) {
+      throw new Error(`Agent ${id} not found in simulation`);
+    }
+    return agent;
+  }
+
+  public getAllAgents(): MogiAgentState[] {
+    return Array.from(this.agents.values());
+  }
+
+  public getSimulationState(): MogiSimulationState {
+    return this.currentState;
+  }
+
+  public async initializeProcess(process: MogiProcess): Promise<void> {
+    this.currentState = {
+      currentProcessId: process.id,
+      activeAgents: Array.from(this.agents.keys()),
+      nodeIndex: 0,
+      isComplete: false,
+    };
+    this.executionQueue = [];
+
+    // Initialize AI Services
+    process.getAIServices().forEach((service) => this.trackAIService(service));
+
+    // Add Process
+    this.processes.push(process);
+
+    // Initialize execution queue
+    for (const agentId of this.currentState.activeAgents) {
+      this.executionQueue.push({
+        processId: process.id,
+        agentId,
+        nodeIndex: 0,
+      });
+    }
+
+    if (this.config.printLogs) {
+      console.log(
+        `Initialized process ${process.id} with agents: ${this.currentState.activeAgents.join(
+          ", "
+        )}`
+      );
+    }
+  }
+
+  public async executeStep(): Promise<boolean> {
+    if (this.currentState.isComplete) return false;
+
+    const currentProcess = this.processes.find((p) => p.id === this.currentState.currentProcessId);
+    if (!currentProcess) {
+      this.currentState.isComplete = true;
+      return false;
+    }
+
+    // Handle conditional processes differently
+    if (currentProcess instanceof MogiConditionalProcess) {
+      return currentProcess.executeConditionalStep(
+        this.currentState.activeAgents.map((id) => this.getAgentState(id)),
+        this.config
+      );
+    }
+
+    // Original linear execution logic
+    const currentNode = currentProcess.nodes[this.currentState.nodeIndex];
+    const agents = this.currentState.activeAgents.map((id) => this.getAgentState(id));
+
+    await Promise.all(agents.map((agent) => currentNode.execute(agent, this.config.delayMs)));
+
+    this.currentState.nodeIndex++;
+    if (this.currentState.nodeIndex >= currentProcess.nodes.length) {
+      this.currentState.isComplete = true;
+    }
+
+    return !this.currentState.isComplete;
+  }
+
+  public async runProcess(process: MogiProcess): Promise<void> {
+    if (this.config.printLogs) console.log(`Process ${process.id} started.`);
+    await this.initializeProcess(process);
+    while (await this.executeStep()) {
+      if (this.config.printLogs)
+        console.log(`Process ${process.id}: Step ${this.currentState.nodeIndex}`);
+      await new Promise((resolve) => setTimeout(resolve, this.config.delayMs));
+    }
+
+    if (this.config.printLogs) console.log(`Process ${process.id} completed.`);
+  }
+
+  private trackAIService(service: AIService): void {
+    if (!this.aiServices.has(service)) {
+      this.aiServices.add(service);
+    }
+  }
+
+  public getAIUsage(): AIUsageStats {
+    return Array.from(this.aiServices).reduce(
+      (acc, service) => {
+        const stats = service.getUsageStats();
+        acc.totalCalls += stats.totalCalls;
+        acc.totalInputTokens += stats.totalInputTokens;
+        acc.totalOutputTokens += stats.totalOutputTokens;
+        acc.estimatedCost += stats.estimatedCost;
+        return acc;
+      },
+      { ...this.globalUsage }
+    );
+  }
+
+  public resetAIUsage(): void {
+    this.aiServices.forEach((service) => service.resetUsageStats());
+    this.globalUsage = {
+      totalCalls: 0,
+      totalInputTokens: 0,
+      totalOutputTokens: 0,
+      estimatedCost: 0,
+    };
+  }
+}
+
+export class MogiProcess {
+  public nodes: MogiNode[] = [];
+  public currentNodeIndex = 0;
+
+  constructor(
+    public readonly id: MogiProcessID,
+    public config: MogiProcessConfig = { retries: 3, timeoutMs: 10000 }
+  ) {}
+
+  addNode(node: MogiNode): this {
+    this.nodes.push(node);
+    return this;
+  }
+
+  async execute(agents: MogiAgentState[], simConfig: MogiSimulationConfig): Promise<void> {
+    for (const agent of agents) {
+      await this.runAgentThroughNodes(agent, simConfig);
+    }
+  }
+
+  private async runAgentThroughNodes(
+    agent: MogiAgentState,
+    simConfig: MogiSimulationConfig
+  ): Promise<void> {
+    for (const node of this.nodes) {
+      await node.execute(agent, simConfig.delayMs);
+      await new Promise((resolve) => setTimeout(resolve, simConfig.delayMs));
+    }
+  }
+
+  public resetExecution(): void {
+    this.currentNodeIndex = 0;
+  }
+
+  public async executeAgentStep(
+    agent: MogiAgentState,
+    simConfig: MogiSimulationConfig
+  ): Promise<boolean> {
+    if (this.currentNodeIndex < this.nodes.length) {
+      await this.nodes[this.currentNodeIndex].execute(agent, simConfig.delayMs);
+      this.currentNodeIndex++;
+      return true;
+    }
+    return false;
+  }
+
+  public getAIServices(): AIService[] {
+    return this.nodes.map((n) => n.getAIService());
+  }
+}
+
+export class MogiNode {
+  constructor(public readonly id: MogiNodeID, private config: MogiNodeConfig) {}
+
+  async execute(agent: MogiAgentState, delayMs: number): Promise<void> {
+    try {
+      const changes = await this.handler(agent);
+      this.applyChanges(agent, changes);
+    } catch (error) {
+      console.error(`MogiNode ${this.id} failed:`, error);
+    }
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+
+  private applyChanges(agent: MogiAgentState, changes: Record<string, any>): void {
+    agent.attributes = { ...agent.attributes, ...changes };
+    agent.history.push({
+      timestamp: new Date(),
+      nodeId: this.id,
+      changes,
+      reasoning: changes._reasoning,
+    });
+  }
+
+  private async handler(agent: MogiAgentState) {
+    const response = this.config.useChainOfThought
+      ? await this.config.aiService.promptThinking(
+          this.config.instructions,
+          JSON.stringify(agent.attributes),
+          this.config.appendMessage ??
+            "Process the JSON object and make changes based on your instructions.",
+          this.config.schema ?? this.config.aiService.createSchema(agent.attributes)
+        )
+      : await this.config.aiService.prompt(
+          this.config.instructions,
+          JSON.stringify(agent.attributes),
+          this.config.appendMessage ??
+            "Process the JSON object and make changes based on your instructions.",
+          this.config.schema ?? this.config.aiService.createSchema(agent.attributes)
+        );
+    return parseAIReponse(response);
+  }
+
+  public getAIService(): AIService {
+    return this.config.aiService;
+  }
+}
+
+// Utility functions
+export function encapsulateSchema(schemas: { [k: string]: Schema }): Schema {
+  return {
+    type: SchemaType.OBJECT,
+    properties: schemas,
+  };
+}
+export function createMogiNode(
+  id: string = crypto.randomUUID(),
+  ai: AIService,
+  instructions: string,
+  schemas?: { [k: string]: Schema },
+  config?: Omit<MogiNodeConfig, "schema" | "aiService" | "instructions">
+): MogiNode {
+  const newNode = new MogiNode(crypto.randomUUID(), {
+    aiService: ai,
+    instructions,
+    useChainOfThought: false,
+    appendMessage: config?.appendMessage,
+    schema: schemas ? encapsulateSchema(schemas) : undefined,
+    ...config,
+  });
+
+  return newNode;
+}
+
+function parseAIReponse(response: AIPromptResponse): Record<string, any> {
+  try {
+    const [jsonStr, reasoning] = Array.isArray(response) ? response : [response];
+    const result = JSON.parse(jsonStr);
+    return { ...result, _reasoning: reasoning };
+  } catch (error) {
+    console.error("Failed to parse AI response:", error);
+    return { _error: "Invalid AI response", _raw: response };
+  }
+}
+
+export class MogiConditionalProcess extends MogiProcess {
+  private condition: (agent: MogiAgentState) => boolean;
+  private trueBranch: MogiProcess;
+  private falseBranch: MogiProcess;
+  private branchStates = new Map<
+    MogiAgentID,
+    {
+      branch: MogiProcess;
+      completed: boolean;
+    }
+  >();
+
+  constructor(
+    id: string,
+    condition: (agent: MogiAgentState) => boolean,
+    trueBranch: MogiProcess,
+    falseBranch: MogiProcess,
+    nodes: MogiNode[] = [],
+    config?: MogiProcessConfig
+  ) {
+    super(id, config);
+    this.condition = condition;
+    this.trueBranch = trueBranch;
+    this.falseBranch = falseBranch;
+    nodes.forEach((n) => this.addNode(n));
+  }
+
+  public async executeConditionalStep(
+    agents: MogiAgentState[],
+    simConfig: MogiSimulationConfig
+  ): Promise<boolean> {
+    let hasMoreSteps = false;
+
+    for (const agent of agents) {
+      if (this.currentNodeIndex < this.nodes.length) {
+        await this.nodes[this.currentNodeIndex].execute(agent, simConfig.delayMs);
+        await new Promise((resolve) => setTimeout(resolve, simConfig.delayMs));
+        hasMoreSteps = true;
+        continue;
+      }
+
+      // Initialize branch state if not set
+      if (!this.branchStates.has(agent.id)) {
+        const branch = this.condition(agent) ? this.trueBranch : this.falseBranch;
+        branch.resetExecution();
+        this.branchStates.set(agent.id, { branch, completed: false });
+      }
+
+      const branchState = this.branchStates.get(agent.id)!;
+      if (!branchState.completed) {
+        const branchHasSteps = await branchState.branch.executeAgentStep(agent, simConfig);
+        if (branchHasSteps) hasMoreSteps = true;
+        branchState.completed = !branchHasSteps;
+      }
+    }
+
+    // Advance main process index if still in base nodes
+    if (this.currentNodeIndex < this.nodes.length) {
+      this.currentNodeIndex++;
+      return true;
+    }
+
+    return hasMoreSteps;
+  }
+
+  public resetExecution(): void {
+    super.resetExecution();
+    this.branchStates.clear();
+    this.trueBranch.resetExecution();
+    this.falseBranch.resetExecution();
+  }
+
+  public updateBranches(trueBranch?: MogiProcess, falseBranch?: MogiProcess): void {
+    if (trueBranch) this.trueBranch = trueBranch;
+    if (falseBranch) this.falseBranch = falseBranch;
+  }
+
+  public getActiveBranch(agentId: MogiAgentID): MogiProcess | null {
+    return this.branchStates.get(agentId)?.branch || null;
+  }
+
+  public getAIServices(): AIService[] {
+    return [...this.nodes, this.trueBranch, this.falseBranch].flatMap((n) => {
+      if (n instanceof MogiProcess) {
+        return n.getAIServices();
+      } else {
+        return n.getAIService();
+      }
+    });
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@channela9/mogi",
+  "version": "0.1.2",
+  "description": "A simulation framework that leverages LLMs to simulate various processes and interactions between agents.",
+  "main": "mogi.ts",
+  "dependencies": {
+    "@google/generative-ai": "^0.21.0"
+  },
+  "devDependencies": {
+    "ts-node": "^10.0.0",
+    "typescript": "^4.0.0"
+  },
+  "keywords": [
+    "simulation",
+    "AI",
+    "LLM",
+    "agents",
+    "process",
+    "interaction",
+    "framework",
+    "nodejs",
+    "typescript"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/channelA9/mogi.git"
+  },
+  "author": "",
+  "license": "MIT",
+  "types": "./mogi.d.ts",
+  "bugs": {
+    "url": "https://github.com/channelA9/mogi/issues"
+  },
+  "homepage": "https://github.com/channelA9/mogi#readme"
+}