mindsim 0.1.0

package/README.md

@@ -0,0 +1,748 @@
+<br/>
+<br/>
+<div align="center">
+    <img style="display: block; width: 250px;" src="assets/mindsim-logo.svg"/>
+</div>
+<br/>
+<br/>
+<br/>
+
+# mindsim-sdk-typescript
+The official MindSim typescript SDK allows you to programmatically create digital minds, populate them with conversational data, and run powerful simulations to get an accurate preview of how the person will think, feel, say, and act in any scenario. 
+
+ Refer to our technical [documentation](https://docs.workflows.com/) to learn more about how to use MinSim.
+
+
+## 📦 Installation
+Pre-requisites before installation
+- Node.js version 24 or higher
+- macOS, Linux, or Windows
+
+
+### Install with NPM
+```
+npm install -g @mindsim/mindsim-sdk-typescript
+```
+
+
+## 🔐 Authentication
+
+The mindsim SDK provides several ways for you to authenticate:
+
+### 1. Using `mindsim auth`
+- Ideal for local development and when you're exploring the possibilities of MindSim and how to integrate the MindSim SDK into your workflows
+
+Example:
+```
+mindsim auth
+```
+
+Then follow the prompts to complete the authentication process. 
+
+### 2. Using environment variables
+- Ideal for deployment scenarios, e.g. CI/CD or in your production applications
+- Set the environment variable `MINDSIM_API_KEY`
+
+Example:
+```bash
+export MINDSIM_API_KEY=<your-api-key>
+```
+
+
+### 3. Passed to the constructor 
+- Ideal for deployment scenarios where secrets are retrieved from a secrets manager at runtime
+
+Example:
+```typescript
+const apiKey = await secrets.load('mindsim_api_key');
+const mindsim = MindSim(apiKey);
+```
+
+
+## 💡 Quick Start Guide
+
+### Build a Mind
+
+The following example shows how you can use the mindsim SDK to create a mind:
+
+```typescript
+import { MindSim } from "@mindsim/mindsim-sdk-typescript";
+import fs from "node:fs";
+import path from "node:path";
+
+const main = async () => {
+  // 1. Instantiate a MindSim client
+  // Ensure you've run `mindsim auth` or MINDSIM_API_KEY is set in env or pass it explicitly
+  const mindsim = new MindSim();
+
+  try {
+    // 2. Create a mind for Bobby Tables
+    const bobby = await mindsim.minds.create({
+      name: "Bobby Tables",
+      email: "bobby@test.com",
+      tags: ["developer"],
+    });
+
+    console.log(`Created Mind: ${bobby.name} (ID: ${bobby.id})`);
+
+    // List of files to process
+    const filePaths = [
+      "./data/chat-history.pdf",
+      "./data/transcript.vtt",
+      "./data/diarized.json"
+    ];
+
+    // 3. Create snapshots for all file
+    await Promise.all(
+      filePaths.map(async (filePath) => {
+        const fileBuffer = fs.readFileSync(filePath);
+        const fileName = path.basename(filePath);
+
+        const response = await mindsim.snapshots.create(bobby.id, {
+          file: fileBuffer,
+          fileName: fileName,
+        });
+
+        // 4. Log status
+        const status = await mindsim.snapshots.getStatus(
+          bobby.id, 
+          response.mindAssessmentId
+        );
+
+        console.log(`File: ${fileName} | Status: ${status.status}`);
+      })
+    );
+
+    console.log("All snapshots processed.");
+
+  } catch (error) {
+    console.error("Error running MindSim workflow:", error);
+  }
+};
+
+main();
+```
+
+### Run Simulations
+
+When MindSim has finished building your mind, you can run simulations on your mind:
+
+```typescript
+import { MindSim } from "@mindsim/mindsim-sdk-typescript";
+
+const main = async () => {
+  const mindsim = new MindSim(process.env.MINDSIM_API_KEY);
+
+  // Existing IDs (e.g., retrieved from database or previous API calls)
+  const mindId = "bobby-tables-id";
+  const snapshotId = "snapshot-123-id";
+
+  try {
+    // 1. Check the status of the snapshot
+    const snapshot = await mindsim.snapshots.getStatus(mindId, snapshotId);
+
+    console.log(`Current Snapshot Status: ${snapshot.status}`);
+
+    switch (snapshot.status) {
+      case "failed":
+        console.error("Error: The snapshot failed to process. Please check file validity.");
+        break;
+
+      case "processing":
+        console.log("Snapshot is still processing. Cannot run simulation yet.");
+        break;
+
+      case "completed":
+        console.log("Snapshot ready. Initiating simulation...");
+
+        // 2. Run the simulation
+        const simulation = await mindsim.simulations.run({
+          mindId: mindId,
+          scenario: {
+            message: "Hey Bobby, I want to merge this PR. What should I include in my PR to maximize the likelihood that you'll accept my changes into the main branch?",
+          },
+        });
+
+        console.log("Simulation Response:", simulation.message);
+        break;
+
+      default:
+        console.log(`Unknown status: ${snapshot.status}`);
+    }
+  } catch (error) {
+    console.error("An error occurred:", error);
+  }
+};
+
+main();
+```
+
+
+## ⚡ Features
+
+### Create Minds
+A mind is a container that represents a person. Think of it as a digital profile.
+
+**What it does**
+- *Stores conversation transcripts* — Upload and manage training data
+- *Holds metadata* — Name, creation date, and configuration
+- *Creates snapshots* — Generate multiple AI models over time as data evolves
+
+Minds are the foundation of MindSim. Each mind represents one person and can have unlimited snapshots trained from different datasets or time periods.
+
+#### Examples
+
+Create a mind
+
+```typescript
+const newMind = await mindsim.minds.create({
+  name: "Sarah Connor",
+  email: "sarah@resistance.org",
+  tags: ["leader", "target"]
+});
+
+console.log(newMind);
+```
+Response:
+```json
+{
+  "id": "ac8ac8c4-05e9-4046-a919-4cbae2f49f22",
+  "name": "Sarah Connor",
+  "email": "sarah@resistance.org",
+  "slug": "sarah-connor",
+  "scope": "private",
+  "isSelf": false,
+  "organizationId": "961b1800-6bd2-444c-8bfa-8dd82b5e80f3",
+  "createdAt": "2023-10-27T10:00:00Z",
+  "updatedAt": "2023-10-27T10:00:00Z",
+  "tags": [
+    { "id": "56255954-189f-4a1e-a355-08a1704af943", "name": "leader" },
+    { "id": "e4d98950-0556-40da-95c8-7de77b3dcbb0", "name": "target" }
+  ]
+}
+```
+---
+List Minds
+
+You can filter the list by passing an array of tag names.
+```typescript
+const developers = await mindsim.minds.list({
+  tags: ["developer", "typescript"], // Passed as an array of strings
+});
+
+console.log(developers);
+```
+
+Response:
+```json
+[
+  {
+    "id": "779e640c-67c2-44e5-bc91-b3b43eeaead8",
+    "name": "Bobby Tables",
+    "email": "bobby@test.com",
+    "scope": "public",
+    "isSelf": false,
+    "tags": [
+      { "id": "e40059db-6bf4-4ef7-ab5b-65ab8610c628", "name": "developer" },
+      { "id": "10eeabd7-96ba-487b-a1e9-2e22957f8536", "name": "typescript" }
+    ]
+  },
+  {
+    "id": "368fcac9-27d8-4cc1-b479-5b9601110086",
+    "name": "Grace Hopper",
+    "email": "grace@navy.mil",
+    "scope": "public",
+    "isSelf": false,
+    "tags": [
+      { "id": "e40059db-6bf4-4ef7-ab5b-65ab8610c628", "name": "developer" }
+    ]
+  }
+]
+```
+
+___
+
+**Search Minds**
+
+```typescript
+const searchResults = await mindsim.minds.search({
+  query: "sarah@resistance.org",
+});
+
+console.log(searchResults);
+```
+
+Response:
+```json
+[
+  {
+    "id": "ac8ac8c4-05e9-4046-a919-4cbae2f49f22",
+    "name": "Sarah Connor",
+    "email": "sarah@resistance.org",
+    "scope": "private",
+    "isSelf": false,
+    "tags": [
+      { "id": "56255954-189f-4a1e-a355-08a1704af943", "name": "leader" }
+    ]
+  }
+]
+```
+---
+Retrieve a Mind
+
+Get the full details of a specific mind by its ID.
+
+```typescript
+const mindId = "ac8ac8c4-05e9-4046-a919-4cbae2f49f22";
+const mind = await mindsim.minds.get(mindId);
+```
+
+Response:
+```json
+{
+  "id": "ac8ac8c4-05e9-4046-a919-4cbae2f49f22",
+  "name": "Sarah Connor",
+  "email": "sarah@resistance.org",
+  "scope": "private",
+  "isSelf": false,
+  "socialMedia": {
+    "twitter": "@sarah_c"
+  },
+  "tags": [
+    { "id": "56255954-189f-4a1e-a355-08a1704af943", "name": "leader" }
+  ]
+}
+```
+---
+Update a Mind
+
+Update the details of an existing mind.
+
+```typescript
+const mindId = "ac8ac8c4-05e9-4046-a919-4cbae2f49f22";
+
+const updatedMind = await mindsim.minds.update(mindId, {
+  name: "Sarah J. Connor",
+  email: "sarah.connor@resistance.net",
+  socialMedia: {
+    twitter: "@sarah_chronicles",
+  },
+  tags: ["leader", "strategist", "human"] // Replaces existing tags
+});
+```
+
+Response:
+```json
+{
+  "id": "ac8ac8c4-05e9-4046-a919-4cbae2f49f22",
+  "name": "Sarah J. Connor",
+  "email": "sarah.connor@resistance.net",
+  "slug": "sarah-j-connor",
+  "scope": "private",
+  "isSelf": false,
+  "organizationId": "961b1800-6bd2-444c-8bfa-8dd82b5e80f3",
+  "createdAt": "2023-10-27T10:00:00Z",
+  "updatedAt": "2023-11-20T14:15:00Z",
+  "socialMedia": {
+    "twitter": "@sarah_chronicles"
+  },
+  "tags": [
+    { "id": "56255954-189f-4a1e-a355-08a1704af943", "name": "leader" },
+    { "id": "a1ca5e66-6f3a-4d92-ab25-8a86fdb111c1", "name": "strategist" },
+    { "id": "b2db6f77-8a4b-5e12-bc36-9b97aec222d2", "name": "human" }
+  ]
+}
+```
+
+**Delete a Mind**
+
+Permanently remove a mind and its associated data.
+
+```typescript
+const mindId = "ac8ac8c4-05e9-4046-a919-4cbae2f49f22";
+const result = await mindsim.minds.delete(mindId);
+```
+
+Response:
+```json
+{
+  "success": true
+}
+```
+---
+Set Tags for a Mind
+
+This operation replaces the existing tags on the mind with the new list provided.
+
+```typescript
+const updatedMind = await mindsim.minds.setTags("ac8ac8c4-05e9-4046-a919-4cbae2f49f22", {
+  tags: ["hero", "survivor"], // Replaces existing tags
+});
+
+console.log(updatedMind.tags);
+```
+
+Response:
+```json
+{
+  "id": "ac8ac8c4-05e9-4046-a919-4cbae2f49f22",
+  "name": "Sarah Connor",
+  "tags": [
+    { 
+      "id": "47a09167-3b9f-442c-a19c-96398cf238fb", 
+      "name": "hero", 
+      "mindCount": 1 
+    },
+    { 
+      "id": "a1ca5e66-6f3a-4d92-ab25-8a86fdb111c1", 
+      "name": "survivor", 
+      "mindCount": 1 
+    }
+  ],
+  // ... other mind properties
+}
+```
+
+
+
+### Upload Snapshots
+A snapshot is a trained AI model built from conversation transcripts. It captures how someone thinks and communicates at a specific point in time.
+
+#### Examples
+
+Create a snapshot (Recommended)
+
+This method automatically generates a signed URL, uploads the file content to the storage provider, and then creates the snapshot record.
+
+```typescript
+import fs from 'node:fs';
+
+const buffer = fs.readFileSync('./data/contract.pdf');
+const mindId = "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d";
+
+const snapshot = await mindsim.snapshots.create(mindId, {
+  file: buffer,
+  fileName: "contract.pdf",
+  contentType: "application/pdf", // If omitted, content type will be inferred from the fileName's extension
+  mindsetDate: "2023-11-01" // Optional: Date associated with the document
+});
+
+console.log(`Snapshot Created! Assessment ID: ${snapshot.mindAssessmentId}`);
+```
+
+Response:
+```json
+{
+  "message": "Snapshot created successfully.",
+  "mindAssessmentId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
+  "artifactId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+}
+```
+---
+
+Create Snapshot from a file
+
+This method uploads the file directly to the MindSim API.
+
+```typescript
+import fs from 'node:fs';
+
+const buffer = fs.readFileSync('./data/chat_logs.txt');
+const mindId = "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d";
+
+const snapshot = await mindsim.snapshots.createFromFile(mindId, {
+  file: buffer,
+  fileName: "chat_logs.txt",
+  // contentType is handled automatically by FormData boundaries
+});
+
+console.log(`Upload Complete. Artifact ID: ${snapshot.artifactId}`);
+```
+
+Response:
+```json
+{
+  "message": "File uploaded successfully.",
+  "mindAssessmentId": "550e8400-e29b-41d4-a716-446655440000",
+  "artifactId": "c56a4180-65aa-42ec-a945-5fd21dec0538"
+}
+```
+---
+
+Snapshot Status
+
+Snapshots process asynchronously. You use the mindAssessmentId (returned from the create calls) as the snapshotId to check progress.
+
+```typescript
+const mindId = "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d";
+const snapshotId = "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11";
+
+const statusInfo = await mindsim.snapshots.getStatus(mindId, snapshotId);
+
+if (statusInfo.status === 'completed') {
+    console.log(`Ready! Finished at: ${statusInfo.completedAt}`);
+} else if (statusInfo.status === 'processing') {
+    console.log(`Still working... Started at: ${statusInfo.startedAt}`);
+} else if (statusInfo.status === 'failed') {
+    console.error("Processing failed.");
+}
+```
+
+Response (Processing):
+```json
+{
+  "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
+  "mindId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+  "status": "processing",
+  "startedAt": "2023-11-15T14:30:00Z",
+  "completedAt": null
+}
+```
+
+Response (Completed):
+```json
+{
+  "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
+  "mindId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+  "status": "completed",
+  "startedAt": "2023-11-15T14:30:00Z",
+  "completedAt": "2023-11-15T14:30:45Z"
+}
+```
+---
+List Snapshots
+
+Retrieve a list of all snapshots (memory banks) associated with a specific mind to track training history.
+
+```typescript
+const mindId = "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d";
+const result = await mindsim.snapshots.list(mindId);
+```
+
+Response:
+```json
+{
+  "count": 2,
+  "snapshots": [
+    {
+      "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
+      "mindId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+      "artifactId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+      "status": "completed",
+      "mindsetDate": "2023-11-01T00:00:00Z",
+      "createdAt": "2023-11-15T14:30:00Z",
+      "completedAt": "2023-11-15T14:30:45Z",
+      "psychometricCount": 12,
+      "keyTopicCount": 5
+    },
+    {
+      "id": "c1ffbd88-0d1a-5fe9-cc7e-7cc8ae491b22",
+      "mindId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+      "artifactId": null,
+      "status": "processing",
+      "mindsetDate": "2023-12-01T00:00:00Z",
+      "createdAt": "2023-12-02T09:15:00Z",
+      "completedAt": null
+    }
+  ]
+}
+```
+
+#### Data Requirements
+
+For the most accurate results, ensure that snapshots conform to the following guidelines.
+
+Minimum data:
+- 10-20 conversations, OR
+- 5,000+ words total
+
+Supported formats:
+- .vtt — Video transcripts (Zoom, Teams, Meet)
+- .pdf — Documents with text
+- .docx — Word documents
+
+Best practices:
+- Use recent data (last 6 months)
+- Include diverse conversation types
+- Ensure transcripts are clean and accurate
+- More data improves accuracy
+
+### Run Simulations
+A simulation predicts how someone would respond to any scenario based on their trained snapshot.
+
+#### Examples
+
+Run a Simulation 
+
+This is the default mode. The request waits until the mind processes the scenario and returns a response.
+```typescript
+const mindId = "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d";
+
+const simulation = await mindsim.simulations.run({
+  mindId: mindId,
+  scenario: {
+    message: "Based on your experience with Python, how would you approach a large data migration?"
+  },
+});
+
+console.log("Mind Response:", simulation.message);
+```
+
+Response:
+```json
+{
+  "message": "Given my background in backend systems, I would prioritize data integrity over speed. I'd likely use a staged approach with Python scripts using Pandas for validation, ensuring we have comprehensive logging for any transformation errors before committing to the production database."
+}
+```
+---
+
+Run a Background Simulation
+
+For automation use cases, it is possible to start simulations without waiting for them to finish. Simulations can then later be retrieved after they have completed for further action.
+
+```typescript
+const mindId = "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d";
+
+// The "reasoning" model performs a chain-of-thought analysis before answering
+const simulation = await mindsim.simulations.run({
+  mindId: mindId,
+  scenario: {
+    message: "Review this git diff and analyze the potential security implications of the auth changes."
+  },
+  runInBackground: true
+});
+
+// When running in background, the API typically acknowledges the queueing of the task
+console.log("Status:", simulation.message);
+```
+
+Response:
+```json
+{
+  "message": "Simulation queued successfully. You will be notified upon completion."
+}
+```
+
+---
+List Simulation History
+
+Retrieve a paginated list of past simulations run by your organization.
+
+```typescript
+const history = await mindsim.simulations.list({
+  limit: 20,
+  offset: 0
+});
+```
+
+Response:
+```json
+{
+  "count": 15,
+  "simulations": [
+    {
+      "id": "123e4567-e89b-12d3-a456-426614174000",
+      "userId": "961b1800-6bd2-444c-8bfa-8dd82b5e80f3",
+      "title": "Simulation with Sarah Connor",
+      "mindId": "ac8ac8c4-05e9-4046-a919-4cbae2f49f22",
+      "createdAt": "2023-11-16T10:00:00Z",
+      "updatedAt": "2023-11-16T10:05:00Z"
+    },
+    {
+      "id": "555e4567-a89b-12d3-b456-426614174999",
+      "userId": "961b1800-6bd2-444c-8bfa-8dd82b5e80f3",
+      "title": "Strategy Meeting Prep",
+      "mindId": "ac8ac8c4-05e9-4046-a919-4cbae2f49f22",
+      "createdAt": "2023-11-14T08:30:00Z",
+      "updatedAt": "2023-11-14T08:35:00Z"
+    },
+    //... the rest of the simulations
+  ]
+}
+```
+
+---
+Retrieve Simulation Details
+
+Get the full transcript (messages) and metadata of a specific simulation.
+
+```typescript
+const simulationId = "123e4567-e89b-12d3-a456-426614174000";
+const fullSimulation = await mindsim.simulations.get(simulationId);
+```
+
+Response:
+```json
+{
+  "simulation": {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "title": "Simulation with Sarah Connor",
+    "userId": "961b1800-6bd2-444c-8bfa-8dd82b5e80f3",
+    "mindId": "ac8ac8c4-05e9-4046-a919-4cbae2f49f22",
+    "createdAt": "2023-11-16T10:00:00Z"
+  },
+  "messages": [
+    {
+      "id": "msg-1",
+      "role": "user",
+      "content": { "text": "What is the biggest threat we face?" },
+      "status": "completed",
+      "createdAt": "2023-11-16T10:00:01Z"
+    },
+    {
+      "id": "msg-2",
+      "role": "assistant",
+      "content": { "text": "Complacency. If we assume the machines are dormant, we lose." },
+      "status": "completed",
+      "createdAt": "2023-11-16T10:00:05Z"
+    }
+  ]
+}
+```
+
+---
+Delete a Simulation
+
+Remove a simulation record from history.
+
+```typescript
+const simulationId = "123e4567-e89b-12d3-a456-426614174000";
+const result = await mindsim.simulations.delete(simulationId);
+```
+
+Response:
+```json
+{
+  "message": "Simulation deleted successfully",
+  "simulationId": "123e4567-e89b-12d3-a456-426614174000"
+}
+```
+
+---
+
+#### Writing Scenarios
+To get the best simulation results, the following best practices are recommended.
+
+**Be Specific**
+
+- ❌ _Vague_: “How would they handle a complaint?” 
+- ✅ _Specific_: “A customer received a damaged product 3 days before their event. They need a replacement by tomorrow, but the product is out of stock. How would you respond?”
+
+**Include Context**
+
+- Emotional state — frustrated, confused, urgent
+- Time constraints — by tomorrow, within 24 hours
+- Constraints — out of stock, over budget
+- Desired outcome — resolution, information
+
+**Add Relevant Details**
+
+- Background information
+- Stakeholder concerns
+- Business constraints
+- Historical context
+
+<br>
+<div align="center">
+    <img style="display: block; margin: auto;" src="assets/mindsim-logo.svg"/>
+</div>