briyah 1.0.3 → 1.0.5

package/.prettierrc

@@ -1,7 +1,7 @@
-{
-  "singleQuote": true,
-  "trailingComma": "all",
-  "tabWidth": 4,
-  "semi": true,
-  "printWidth": 9999
-}
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "tabWidth": 4,
+  "semi": true,
+  "printWidth": 9999
+}

package/README.md

@@ -0,0 +1,402 @@
+# Briyah SDK
+
+The Briyah SDK provides a clean, easy-to-use interface for integrating the Briyah multi-agent AI system into your applications without requiring NestJS dependency injection setup.
+
+## Installation
+
+```bash
+npm install briyah
+```
+
+```typescript
+import { Briyah } from 'briyah';
+```
+
+## Quick Start
+
+```typescript
+import { Briyah } from 'briyah';
+
+// 1. Create and initialize Briyah instance
+const briyah = new Briyah({
+    dataPath: './my-briyah-data',
+    userServiceCacheTimeoutMinutes: 30,
+    startingBalance: 10.00
+});
+
+await briyah.init();
+
+// 2. Get user-specific service (userId managed by your app)
+const appService = briyah.getAppService('user-123');
+
+// 3. Use full Briyah functionality
+// createAgent() registers the agent in memory immediately — agent.id is usable right away.
+// Call agent.save() when you want to persist it to disk.
+const agent = appService.createAgent(
+    'Anthropic',
+    'Assistant',
+    'Assistant',
+    'A helpful AI assistant',
+    'claude-3-5-sonnet-20241022'
+);
+
+if (!agent.id) throw new Error('Agent creation failed');
+const result = await appService.processText(agent.id, 'Hello! How are you?');
+console.log(result.result);
+
+agent.save(); // persist to disk
+
+// 4. Cleanup when done
+await briyah.shutdown();
+```
+
+## Configuration
+
+### BriyahConfigOptions
+
+```typescript
+interface BriyahConfigOptions {
+    /**
+     * Base directory for Briyah data storage
+     * Default: './data' relative to process.cwd()
+     */
+    dataPath?: string;
+
+    /**
+     * Timeout in minutes for cached user services
+     * Default: 30 minutes
+     */
+    userServiceCacheTimeoutMinutes?: number;
+
+    /**
+     * Starting balance for new users (in dollars)
+     * Default: value from process.env.STARTING_BALANCE
+     */
+    startingBalance?: number;
+
+    /**
+     * Override environment variables
+     * Useful for testing or multi-instance configurations
+     */
+    envOverrides?: Record<string, string>;
+}
+```
+
+### Environment Variables
+
+Briyah requires certain environment variables to be set:
+
+**Required:**
+- `STARTING_BALANCE` - Starting balance for new users (e.g., "10.00")
+
+**LLM Provider API Keys** (at least one required):
+- `ANTHROPIC_API_KEY` - For Claude models
+- `OPENAI_API_KEY` - For GPT models
+- `GOOGLE_VERTEX_PROJECT_ID` - For Google Vertex AI
+- `XAI_API_KEY` - For Grok models
+- `DEEPSEEK_API_KEY` - For DeepSeek models
+- `TOGETHER_API_KEY` - For Together AI models
+
+**Optional:**
+- `SERVER_DATA_PATH` - Global default data path (overridden by constructor `dataPath`)
+- `USER_SERVICE_CACHE_TIMEOUT_MINUTES` - Cache timeout (overridden by constructor option)
+
+## API Reference
+
+### Briyah Class
+
+#### constructor(options?: BriyahConfigOptions)
+
+Creates a new Briyah SDK instance.
+
+```typescript
+const briyah = new Briyah({
+    dataPath: './briyah-data',
+    startingBalance: 10.00
+});
+```
+
+#### async init(): Promise\<void\>
+
+Initializes the Briyah system. Must be called before using `getAppService()`.
+
+```typescript
+await briyah.init();
+```
+
+#### getAppService(userId: string): AppService
+
+Gets the AppService instance for a specific user. The AppService provides full access to:
+- Agent management
+- Room conversations
+- Story generation
+- Text processing
+- File attachments
+
+```typescript
+const appService = briyah.getAppService('user-123');
+```
+
+**Throws:** Error if `init()` has not been called.
+
+#### removeUserService(userId: string): void
+
+Manually removes a user's service from the cache. Useful for:
+- Forcing a fresh AppService instance
+- Cleaning up when a user logs out
+
+```typescript
+briyah.removeUserService('user-123');
+```
+
+#### getCacheStats()
+
+Returns statistics about cached user services.
+
+```typescript
+const stats = briyah.getCacheStats();
+console.log(`Cached users: ${stats.cachedUsers}`);
+```
+
+#### async shutdown(): Promise\<void\>
+
+Shuts down the Briyah system and cleans up resources.
+
+```typescript
+await briyah.shutdown();
+```
+
+#### isInitialized(): boolean
+
+Checks if Briyah has been initialized.
+
+```typescript
+if (briyah.isInitialized()) {
+    const appService = briyah.getAppService('user-123');
+}
+```
+
+### AppService
+
+The AppService provides full access to Briyah functionality.
+
+**Common operations:**
+
+```typescript
+// Agent Management
+const agent = appService.createAgent(provider, name, nickname, description, model);
+const agents = await appService.listAgents();
+await appService.deleteAgent(agentId);
+
+// Room Management
+const room = await appService.createRoom(name, goal, agentIds);
+const rooms = await appService.listRooms();
+await appService.sendRoomMessage(roomId, content, sender, action?);
+
+// Story Management
+const story = await appService.createStory(name, idea, userCharacterDesc, otherCharactersDesc, storyModel?);
+await appService.progressStory(storyId);
+
+// Text Processing
+const result = await appService.processText(agentId, text);
+
+// File Attachments
+const attachment = await appService.attachDocument(agentId, fileName, fileData);
+await appService.deleteAttachedFile(agentId, fileName);       // by filename
+await appService.deleteAttachedFileById(documentId);           // by document ID
+```
+
+## Usage Examples
+
+### Example 1: Multi-User Setup
+
+```typescript
+import { Briyah } from 'briyah';
+
+// Initialize once at application startup
+const briyah = new Briyah({
+    dataPath: './data/briyah',
+    startingBalance: 10.00
+});
+
+await briyah.init();
+
+// In your route handler or service
+async function handleUserRequest(userId: string, message: string) {
+    const appService = briyah.getAppService(userId);
+
+    // Each user gets their own isolated AppService
+    const agents = await appService.listAgents();
+
+    // ... process user request
+}
+
+// Cleanup at application shutdown
+process.on('SIGINT', async () => {
+    await briyah.shutdown();
+    process.exit(0);
+});
+```
+
+### Example 2: Custom Data Path
+
+```typescript
+import { Briyah } from 'briyah';
+import path from 'path';
+
+const briyah = new Briyah({
+    dataPath: path.join(__dirname, '..', 'user-data', 'briyah'),
+    userServiceCacheTimeoutMinutes: 60 // 1 hour cache
+});
+
+await briyah.init();
+```
+
+### Example 3: Testing Configuration
+
+```typescript
+import { Briyah } from 'briyah';
+
+const testBriyah = new Briyah({
+    dataPath: './test-data',
+    startingBalance: 100.00,
+    userServiceCacheTimeoutMinutes: 5,
+    envOverrides: {
+        ANTHROPIC_API_KEY: process.env.TEST_ANTHROPIC_KEY,
+        OPENAI_API_KEY: process.env.TEST_OPENAI_KEY
+    }
+});
+
+await testBriyah.init();
+
+// Run tests...
+
+await testBriyah.shutdown();
+```
+
+### Example 4: Agent Creation and Text Processing
+
+```typescript
+const appService = briyah.getAppService('user-123');
+
+// Create an agent
+const agent = appService.createAgent(
+    'Anthropic',           // provider
+    'Assistant',           // name
+    'Assistant',           // nickname
+    'Helpful AI',          // description
+    'claude-3-5-sonnet-20241022'  // model
+);
+
+if (!agent.id) throw new Error('Agent creation failed');
+console.log(`Created agent: ${agent.id}`);
+
+// Process text with the agent
+const result = await appService.processText(
+    agent.id,
+    'What is the capital of France?'
+);
+
+console.log(`Response: ${result.result}`);
+console.log(`Cost: $${result.totalCost}`);
+console.log(`Tokens: ${(result.totalInputTokens ?? 0) + (result.totalOutputTokens ?? 0)}`);
+```
+
+### Example 5: Multi-Agent Room Conversation
+
+```typescript
+const appService = briyah.getAppService('user-123');
+
+// Create agents
+const analyst = appService.createAgent('OpenAI', 'Analyst', 'Analyst', 'Data analyst', 'gpt-4');
+const writer = appService.createAgent('Anthropic', 'Writer', 'Writer', 'Content writer', 'claude-3-5-sonnet-20241022');
+
+if (!analyst.id || !writer.id) throw new Error('Agent creation failed');
+
+// Create a room with both agents
+const room = await appService.createRoom(
+    'Analysis Session',
+    'Analyze sales data and produce a written summary',
+    [analyst.id, writer.id]
+);
+
+// Send a message to start the conversation
+await appService.sendRoomMessage(
+    room.roomId,
+    'Please analyze the sales data for Q4',
+    'Analyst',
+    'speak'
+);
+
+// The agents will automatically respond and interact
+// Check room messages to see the conversation
+const messages = await appService.getRoomMessages(room.roomId);
+console.log(`Messages: ${messages.messages.length}`);
+```
+
+## Data Storage
+
+Briyah stores data in the following structure:
+
+```
+{dataPath}/
+├── common/                      # Shared across all users
+│   ├── creds/                   # Service account credentials
+│   ├── prices/                  # LLM pricing data
+│   ├── prompts/                 # Global prompt templates
+│   └── published-agents.json    # Published agent mappings
+└── user/
+    └── {userId}/                # Per-user data
+        ├── prompts/             # User-specific prompts
+        ├── upload/              # User file attachments
+        └── userconfig/          # User configuration files
+            ├── agents.json      # User's agents
+            ├── rooms.json       # User's rooms
+            ├── stories.json     # User's stories
+            └── balance.json     # User's balance
+```
+
+## Multi-Instance Support
+
+You can create multiple Briyah instances with different configurations:
+
+```typescript
+const briyah1 = new Briyah({ dataPath: './data1' });
+const briyah2 = new Briyah({ dataPath: './data2' });
+
+await briyah1.init();
+await briyah2.init();
+
+// Each instance has isolated data
+const user1Service = briyah1.getAppService('user-123');
+const user2Service = briyah2.getAppService('user-123');
+// These are completely separate services with different data paths
+```
+
+**Note:** Singleton services (LLM providers, message emitters) are shared across all Briyah instances within the same process. This is safe because they are stateless or keyed by ID.
+
+## Backward Compatibility
+
+The Briyah SDK is fully backward compatible with the existing NestJS application. The NestJS app continues to work without any changes, while new applications can use the SDK for simplified integration.
+
+## Troubleshooting
+
+### "Must call init() before getAppService()"
+
+Make sure to call `await briyah.init()` before calling `getAppService()`.
+
+### "No LLM provider API keys configured"
+
+Set at least one of the required API key environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.).
+
+### "STARTING_BALANCE environment variable is required"
+
+Set the `STARTING_BALANCE` environment variable or pass `startingBalance` in the constructor options.
+
+### Cache not working as expected
+
+Check the cache statistics with `getCacheStats()` and adjust `userServiceCacheTimeoutMinutes` in the constructor options.
+
+## Support
+
+For issues or questions, please refer to the main Briyah documentation or create an issue in the repository.

package/dist/server/src/ai/agent-store.service.d.ts

@@ -16,6 +16,7 @@ export declare class AgentStoreService {
     private loadPromise;
     constructor(aiFactoryService: AiFactoryService, configService: ConfigurationService, attachedFileService: AttachedFileService, balanceService: BalanceService, artifactService: ArtifactService);
     getDefaultStorageDir(): string;
+    registerAgent(agent: Agent): void;
     storeAgent(agent: Agent, storageDir?: string): string;
     getAgent(id: string): Promise<Agent | undefined>;
     removeAgent(id: string): boolean;

package/dist/server/src/ai/agent-store.service.js

@@ -74,6 +74,12 @@ let AgentStoreService = class AgentStoreService {
     getDefaultStorageDir() {
         return this.defaultStorageDir;
     }
+    registerAgent(agent) {
+        if (!agent.id) {
+            agent.id = (0, crypto_1.randomUUID)();
+        }
+        this.agents.set(agent.id, agent);
+    }
     storeAgent(agent, storageDir) {
         if (!agent.id) {
             agent.id = (0, crypto_1.randomUUID)();

package/dist/server/src/app.service.js

@@ -170,6 +170,7 @@ class AppService {
             agent.beginInstruction = beginInstruction;
         }
         this.setupAgentStateCallback(agent);
+        this.agentStore.registerAgent(agent);
         return agent;
     }
     async processText(agentId, text) {

package/dist/server/src/room/artifact-store.service.js

@@ -210,10 +210,10 @@ let ArtifactStoreService = ArtifactStoreService_1 = class ArtifactStoreService {
         const viewersStr = artifact.viewers && artifact.viewers.length > 0
             ? artifact.viewers.join(', ')
             : artifact.creator;
-        return `# name: ${artifact.name}
-# creator: ${artifact.creator}
-# viewers: ${viewersStr}
-
+        return `# name: ${artifact.name}
+# creator: ${artifact.creator}
+# viewers: ${viewersStr}
+
 ${artifact.body}`;
     }
     getArtifactFilePath(roomId, storageDir, sanitizedName) {

package/eslint.config.js

@@ -1,29 +1,29 @@
-const tseslint = require('@typescript-eslint/eslint-plugin');
-const tsparser = require('@typescript-eslint/parser');
-
-module.exports = [
-  {
-    ignores: ['dist/**', 'node_modules/**', 'data/**', 'coverage/**'],
-  },
-  {
-    files: ['**/*.ts'],
-    languageOptions: {
-      parser: tsparser,
-      parserOptions: {
-        project: './tsconfig.json',
-        tsconfigRootDir: __dirname,
-        sourceType: 'module',
-      },
-    },
-    plugins: {
-      '@typescript-eslint': tseslint,
-    },
-    rules: {
-      ...tseslint.configs['recommended'].rules,
-      '@typescript-eslint/interface-name-prefix': 'off',
-      '@typescript-eslint/explicit-function-return-type': 'off',
-      '@typescript-eslint/explicit-module-boundary-types': 'off',
-      '@typescript-eslint/no-explicit-any': 'off',
-    },
-  },
-];
+const tseslint = require('@typescript-eslint/eslint-plugin');
+const tsparser = require('@typescript-eslint/parser');
+
+module.exports = [
+  {
+    ignores: ['dist/**', 'node_modules/**', 'data/**', 'coverage/**'],
+  },
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        project: './tsconfig.json',
+        tsconfigRootDir: __dirname,
+        sourceType: 'module',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+    },
+    rules: {
+      ...tseslint.configs['recommended'].rules,
+      '@typescript-eslint/interface-name-prefix': 'off',
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "briyah",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Briyah multi-agent AI SDK",
   "private": false,
   "main": "dist/server/src/sdk/index.js",
@@ -16,6 +16,7 @@
     "prebuild": "rimraf dist",
     "build": "nest build",
     "build:sdk": "rimraf dist && tsc -p tsconfig.build.json",
+    "publish:sdk": "npm run build:sdk && npm publish",
     "prepublishOnly": "npm run build:sdk",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "start": "nest start",