feat(agents): Initial commit

Author: grypez

packages/agents/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/MetaMask/ocap-kernel/

packages/agents/README.md

@@ -0,0 +1,15 @@
+# `@ocap/agents`
+
+A starting point for LLM integration
+
+## Installation
+
+`yarn add @ocap/agents`
+
+or
+
+`npm install @ocap/agents`
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/ocap-kernel#readme).

packages/agents/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@ocap/agents",
+  "version": "0.0.0",
+  "private": true,
+  "description": "A starting point for LLM integration",
+  "homepage": "https://github.com/MetaMask/ocap-kernel/tree/main/packages/agents#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/ocap-kernel/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/ocap-kernel.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --clean",
+    "build:docs": "typedoc",
+    "changelog:validate": "../../scripts/validate-changelog.sh @ocap/agents",
+    "clean": "rimraf --glob './*.tsbuildinfo' ./.eslintcache ./coverage ./dist",
+    "lint": "yarn lint:eslint && yarn lint:misc --check && yarn constraints && yarn lint:dependencies",
+    "lint:dependencies": "depcheck",
+    "lint:eslint": "eslint . --cache",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write && yarn constraints --fix && yarn lint:dependencies",
+    "lint:misc": "prettier --no-error-on-unmatched-pattern '**/*.json' '**/*.md' '**/*.html' '!**/CHANGELOG.old.md' '**/*.yml' '!.yarnrc.yml' '!merged-packages/**' --ignore-path ../../.gitignore",
+    "publish:preview": "yarn npm publish --tag preview",
+    "test": "vitest run --config vitest.config.ts",
+    "test:clean": "yarn test --no-cache --coverage.clean",
+    "test:dev": "yarn test --mode development",
+    "test:verbose": "yarn test --reporter verbose",
+    "test:watch": "vitest --config vitest.config.ts"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.17.4",
+    "@metamask/auto-changelog": "^5.0.1",
+    "@metamask/eslint-config": "^14.0.0",
+    "@metamask/eslint-config-nodejs": "^14.0.0",
+    "@metamask/eslint-config-typescript": "^14.0.0",
+    "@metamask/logger": "workspace:^",
+    "@metamask/ocap-kernel": "workspace:^",
+    "@ocap/cli": "workspace:^",
+    "@ocap/nodejs": "workspace:^",
+    "@ocap/test-utils": "workspace:^",
+    "@ts-bridge/cli": "^0.6.3",
+    "@ts-bridge/shims": "^0.1.1",
+    "@types/node": "^22.13.1",
+    "@typescript-eslint/eslint-plugin": "^8.29.0",
+    "@typescript-eslint/parser": "^8.29.0",
+    "@typescript-eslint/utils": "^8.29.0",
+    "@vitest/eslint-plugin": "^1.1.44",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.23.0",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-import-resolver-typescript": "^4.3.1",
+    "eslint-plugin-import-x": "^4.10.0",
+    "eslint-plugin-jsdoc": "^50.6.9",
+    "eslint-plugin-n": "^17.17.0",
+    "eslint-plugin-prettier": "^5.2.6",
+    "eslint-plugin-promise": "^7.2.1",
+    "prettier": "^3.5.3",
+    "rimraf": "^6.0.1",
+    "typedoc": "^0.28.1",
+    "typescript": "~5.8.2",
+    "typescript-eslint": "^8.29.0",
+    "vite": "^6.3.5",
+    "vitest": "^3.1.3"
+  },
+  "engines": {
+    "node": "^20 || >=22"
+  },
+  "dependencies": {
+    "@endo/far": "^1.1.11",
+    "@metamask/streams": "workspace:^",
+    "ollama": "^0.5.16"
+  }
+}

packages/agents/src/index.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+
+import greet from './index.ts';
+
+describe('Test', () => {
+  it('greets', () => {
+    const name = 'Huey';
+    const result = greet(name);
+    expect(result).toBe('Hello, Huey!');
+  });
+});

packages/agents/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Example function that returns a greeting for the given name.
+ *
+ * @param name - The name to greet.
+ * @returns The greeting.
+ */
+export default function greet(name: string): string {
+  return `Hello, ${name}!`;
+}

packages/agents/src/llm.test.ts

@@ -0,0 +1,52 @@
+import '@ocap/test-utils/mock-endoify';
+import { consoleTransport, Logger } from '@metamask/logger';
+import { kunser } from '@metamask/ocap-kernel';
+import type { Kernel } from '@metamask/ocap-kernel';
+import { makeKernel } from '@ocap/nodejs';
+import { expect, describe, it, beforeEach } from 'vitest';
+
+import { getBundleSpec } from './vats/index.ts';
+
+const logger = new Logger({
+  tags: ['test'],
+  transports: [consoleTransport],
+});
+
+describe('llm', () => {
+  let kernel: Kernel;
+  beforeEach(async () => {
+    const { port2: port } = new MessageChannel();
+    kernel = await makeKernel({
+      port,
+      dbFilename: ':memory:',
+      logger,
+    });
+  });
+
+  it(
+    'should be able to generate text',
+    {
+      timeout: 5_000,
+    },
+    async () => {
+      console.log('Starting test');
+      const prompt = 'Count to 6. Do not use any words.';
+      const result = await kernel.launchSubcluster({
+        bootstrap: 'user',
+        vats: {
+          user: {
+            bundleSpec: getBundleSpec('user'),
+            parameters: { name: 'Alice', prompt },
+          },
+          ollama: {
+            bundleSpec: getBundleSpec('ollama'),
+          },
+        },
+      });
+      expect(result).toBeDefined();
+      const llmResponse = kunser(result as Parameters<typeof kunser>[0]);
+      expect(typeof llmResponse).toBe('string');
+      expect(llmResponse).toMatch(/1[^0-9]*2[^0-9]*3[^0-9]*4[^0-9]*5/u);
+    },
+  );
+});

packages/agents/src/llm.ts

@@ -0,0 +1,55 @@
+import { makeFarGenerator } from '@metamask/streams/vat';
+import type { Config as OllamaConfig, Message as ChatMessage } from 'ollama';
+import { Ollama } from 'ollama/browser';
+
+const defaultConfig = {
+  model: 'llama3.2:latest',
+  baseUrl: 'http://localhost:11434',
+};
+
+export type Llm = Awaited<ReturnType<typeof makeLlm>>;
+
+/**
+ * Connect to a local LLM instance.
+ *
+ * @param config - The configuration for the LLM.
+ * @returns An LLM instance.
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export async function makeLlm(config: Partial<OllamaConfig> = {}) {
+  const ollamaConfig = { ...defaultConfig, ...config };
+  const ollama = new Ollama(ollamaConfig);
+  const { model } = ollamaConfig;
+  // await ollama.pull({ model });
+
+  /**
+   * Generate a response from the LLM.
+   *
+   * @param prompt - The prompt to generate a response for.
+   * @returns An iterator that yields the response.
+   */
+  // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+  const generate = async (prompt: string) => {
+    const response = await ollama.generate({ model, prompt, stream: true });
+    const iterator = response[Symbol.asyncIterator]();
+    return makeFarGenerator(iterator);
+  };
+
+  /**
+   * Chat with the LLM.
+   *
+   * @param messages - The messages to chat with.
+   * @returns An iterator that yields the response.
+   */
+  // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+  const chat = async (messages: ChatMessage[]) => {
+    const response = await ollama.chat({ model, messages, stream: true });
+    const iterator = response[Symbol.asyncIterator]();
+    return makeFarGenerator(iterator);
+  };
+
+  return {
+    generate,
+    chat,
+  };
+}

packages/agents/src/vats/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Get the bundle spec for a given bundle name.
+ *
+ * @param bundleName - The name of the bundle.
+ * @returns The bundle spec.
+ */
+export const getBundleSpec = (bundleName: string): string => {
+  try {
+    return `file://${new URL(`./${bundleName}.bundle`, import.meta.url).pathname}`;
+  } catch (error) {
+    throw new Error(
+      `Failed to getBundleSpec for ${bundleName}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    );
+  }
+};

packages/agents/src/vats/ollama.js

@@ -0,0 +1,14 @@
+import { Far } from '@endo/far';
+
+import { makeLlm } from '../llm.ts';
+
+/**
+ * Build the root object for an ollama vat.
+ *
+ * @returns {object} The root object.
+ */
+export async function buildRootObject() {
+  return Far('root', {
+    makeLlm: async (config) => Far('llm', { ...(await makeLlm(config)) }),
+  });
+}

packages/agents/src/vats/user.js

@@ -0,0 +1,32 @@
+import { E, Far } from '@endo/far';
+// eslint-disable-next-line import-x/no-unresolved
+import { makeEventualIterator } from '@metamask/streams/vat';
+
+/**
+ * Build the root object for a synthetic user.
+ *
+ * @param {*} _ - Unused.
+ * @param {*} parameters - The parameters to use to build the root object.
+ * @param {string} parameters.name - The name of the user.
+ * @param {string} parameters.prompt - The prompt the user gives to the LLM.
+ *
+ * @returns {object} The root object.
+ */
+export function buildRootObject(_, { name, prompt }) {
+  let llm;
+  return Far(`user:${name}`, {
+    bootstrap: async ({ ollama }, _services) => {
+      console.log('Bootstrapping user');
+      llm = await E(ollama).makeLlm();
+      const responseStream = makeEventualIterator(
+        await E(llm).generate(prompt),
+      );
+      let response = '';
+      for await (const chunk of responseStream) {
+        response += chunk.response;
+        console.log(chunk.response);
+      }
+      return response;
+    },
+  });
+}