@promptbook/openai 0.103.0-43 → 0.103.0-45

package/esm/typings/src/collection/agent-collection/AgentCollection.d.ts

@@ -1,8 +1,4 @@
-import type { Promisable } from 'type-fest';
-import type { AgentBasicInformation } from '../../book-2.0/agent-source/AgentBasicInformation';
-import type { string_book } from '../../book-2.0/agent-source/string_book';
-import { Agent } from '../../llm-providers/agent/Agent';
-import type { string_agent_name } from '../../types/typeAliases';
+import { AgentCollectionInSupabase } from './constructors/agent-collection-in-supabase/AgentCollectionInSupabase';
 /**
  * Collection that groups together multiple AI Agents
  *
@@ -10,29 +6,7 @@ import type { string_agent_name } from '../../types/typeAliases';
  * - `AgentCollection` - which groups together AI Agents
  * - `PipelineCollection` - which groups together *(deprecated)* pipelines
  */
-export type AgentCollection = {
-    /**
-     * Gets all agents in the collection
-     */
-    listAgents(): Promisable<ReadonlyArray<AgentBasicInformation>>;
-    /**
-     * Get one agent by its name
-     *
-     * Note: !!!! Agents are existing independently of you getting them or not, you can get the same agent multiple times.
-     * Note: Agents are changed by interacting with `Agent` objects directly. Only creation and deletion is done via the collection.
-     */
-    spawnAgent(agentName: string_agent_name): Promisable<Agent>;
-    /**
-     * Creates a new agent in the collection
-     *
-     * Note: You can set 'PARENT' in the agent source to inherit from another agent in the collection.
-     */
-    createAgent(agentSource: string_book): Promisable<AgentBasicInformation>;
-    /**
-     * Deletes an agent from the collection
-     */
-    deleteAgent(agentName: string_agent_name): Promisable<void>;
-};
+export type AgentCollection = AgentCollectionInSupabase;
 /**
  * TODO: [🧠][🚙] `AgentXxx` vs `AgentsXxx` naming convention
  */

package/esm/typings/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

@@ -1,12 +1,10 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
+import { BehaviorSubject } from 'rxjs';
 import type { AgentBasicInformation } from '../../../../book-2.0/agent-source/AgentBasicInformation';
 import type { string_book } from '../../../../book-2.0/agent-source/string_book';
 import type { CommonToolsOptions } from '../../../../execution/CommonToolsOptions';
-import type { ExecutionTools } from '../../../../execution/ExecutionTools';
-import { Agent } from '../../../../llm-providers/agent/Agent';
 import type { PrepareAndScrapeOptions } from '../../../../prepare/PrepareAndScrapeOptions';
 import type { string_agent_name } from '../../../../types/typeAliases';
-import type { AgentCollection } from '../../AgentCollection';
 import type { AgentsDatabaseSchema } from './AgentsDatabaseSchema';
 /**
  * Agent collection stored in Supabase table
@@ -16,28 +14,81 @@ import type { AgentsDatabaseSchema } from './AgentsDatabaseSchema';
  * @public exported from `@promptbook/core`
  * <- TODO: !!! Move to `@promptbook/supabase` package
  */
-export declare class AgentCollectionInSupabase implements AgentCollection {
+export declare class AgentCollectionInSupabase {
     private readonly supabaseClient;
-    private readonly tools?;
     readonly options?: (PrepareAndScrapeOptions & CommonToolsOptions) | undefined;
     /**
      * @param rootPath - path to the directory with agents
-     * @param tools - Execution tools to be used in `Agent` itself and listing the agents
+     * @param tools - Execution tools to be used in !!! `Agent` itself and listing the agents
      * @param options - Options for the collection creation
      */
-    constructor(supabaseClient: SupabaseClient<AgentsDatabaseSchema>, tools?: Pick<ExecutionTools, "llm" | "fs" | "scrapers"> | undefined, options?: (PrepareAndScrapeOptions & CommonToolsOptions) | undefined);
+    constructor(supabaseClient: SupabaseClient<AgentsDatabaseSchema>, options?: (PrepareAndScrapeOptions & CommonToolsOptions) | undefined);
     /**
      * Cached defined execution tools
      */
-    private _definedTools;
     /**
      * Gets all agents in the collection
      */
     listAgents(): Promise<ReadonlyArray<AgentBasicInformation>>;
     /**
      * !!!
+     * /
+    public async spawnAgent(agentName: string_agent_name): Promise<Agent> {
+   
+        // <- TODO: !!! ENOENT: no such file or directory, open 'C:\Users\me\work\ai\promptbook\agents\examples\Asistent pro LŠVP.book
+        const { isVerbose = DEFAULT_IS_VERBOSE } = this.options || {};
+        const tools = await this.getTools();
+
+        const agentSourceValue = validateBook(await tools.fs!.readFile(agentSourcePath, 'utf-8'));
+        const agentSource = new BehaviorSubject(agentSourceValue);
+
+        // Note: Write file whenever agent source changes
+        agentSource.subscribe(async (newSource) => {
+            if (isVerbose) {
+                console.info(colors.cyan(`Writing agent source to file ${agentSourcePath}`));
+            }
+            await forTime(500); // <- TODO: [🙌] !!! Remove
+            await tools.fs!.writeFile(agentSourcePath, newSource, 'utf-8');
+        });
+
+        // Note: Watch file for external changes
+        for await (const event of tools.fs!.watch(agentSourcePath)) {
+            // <- TODO: !!!! Solve the memory freeing when the watching is no longer needed
+
+            if (event.eventType !== 'change') {
+                continue;
+            }
+
+            if (isVerbose) {
+                console.info(
+                    colors.cyan(`Detected external change in agent source file ${agentSourcePath}, reloading`),
+                );
+            }
+            await forTime(500); // <- TODO: [🙌] !!! Remove
+            const newSource = validateBook(await tools.fs!.readFile(agentSourcePath, 'utf-8'));
+            agentSource.next(newSource);
+        }
+
+        // TODO: [🙌] !!!! Debug the infinite loop when file is changed externally and agent source is updated which causes file to be written again
+
+        const agent = new Agent({
+            ...this.options,
+            agentSource,
+            executionTools: this.tools || {},
+        });
+
+        if (isVerbose) {
+            console.info(colors.cyan(`Created agent "${agent.agentName}" from source file ${agentSourcePath}`));
+        }
+
+        return agent;
+        * /
+    }
+    */
+    /**
+     * !!!@@@
      */
-    spawnAgent(agentName: string_agent_name): Promise<Agent>;
+    getAgentSource(agentName: string_agent_name): Promise<BehaviorSubject<string_book>>;
     /**
      * Creates a new agent in the collection
      *
@@ -50,6 +101,7 @@ export declare class AgentCollectionInSupabase implements AgentCollection {
     deleteAgent(agentName: string_agent_name): Promise<void>;
 }
 /**
+ * TODO: !!!! Implement it here correctly and update JSDoc comments here, and on interface + other implementations
  * TODO: Write unit test
  * TODO: [🧠][🚙] `AgentXxx` vs `AgentsXxx` naming convention
  */

package/esm/typings/src/errors/DatabaseError.d.ts

@@ -7,3 +7,6 @@ export declare class DatabaseError extends Error {
     readonly name = "DatabaseError";
     constructor(message: string);
 }
+/**
+ * TODO: !!!! Explain that NotFoundError (!!! and other specific errors) has priority over DatabaseError in some contexts
+ */ 

package/esm/typings/src/llm-providers/_multiple/getSingleLlmExecutionTools.d.ts

@@ -7,5 +7,6 @@ import { MultipleLlmExecutionTools } from './MultipleLlmExecutionTools';
  */
 export declare function getSingleLlmExecutionTools(oneOrMoreLlmExecutionTools: undefined | LlmExecutionTools | ReadonlyArray<LlmExecutionTools>): LlmExecutionTools | MultipleLlmExecutionTools;
 /**
+ * TODO: [🙆] `getSingleLlmExecutionTools` vs `joinLlmExecutionTools` - explain difference or pick one
  * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
  */

package/esm/typings/src/llm-providers/_multiple/joinLlmExecutionTools.d.ts

@@ -18,5 +18,6 @@ import { MultipleLlmExecutionTools } from './MultipleLlmExecutionTools';
  */
 export declare function joinLlmExecutionTools(title: string_title & string_markdown_text, ...llmExecutionTools: ReadonlyArray<LlmExecutionTools>): MultipleLlmExecutionTools;
 /**
+ * TODO: [🙆] `getSingleLlmExecutionTools` vs `joinLlmExecutionTools` - explain difference or pick one
  * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
  */

package/esm/typings/src/llm-providers/agent/CreateAgentLlmExecutionToolsOptions.d.ts

@@ -1,10 +1,11 @@
 import type { string_book } from '../../book-2.0/agent-source/string_book';
+import { CommonToolsOptions } from '../../execution/CommonToolsOptions';
 import type { LlmExecutionTools } from '../../execution/LlmExecutionTools';
 import { OpenAiAssistantExecutionTools } from '../openai/OpenAiAssistantExecutionTools';
 /**
  * Options for creating AgentLlmExecutionTools
  */
-export type CreateAgentLlmExecutionToolsOptions = {
+export type CreateAgentLlmExecutionToolsOptions = CommonToolsOptions & {
     /**
      * The underlying LLM execution tools to wrap
      */

package/esm/typings/src/llm-providers/anthropic-claude/anthropic-claude-models.d.ts

@@ -3,7 +3,7 @@ import type { number_usd } from '../../types/typeAliases';
 /**
  * List of available Anthropic Claude models with pricing
  *
- * Note: Synced with official API docs at 2025-08-20
+ * Note: Synced with official API docs at 2025-11-19
  *
  * @see https://docs.anthropic.com/en/docs/models-overview
  * @public exported from `@promptbook/anthropic-claude`

package/esm/typings/src/llm-providers/google/google-models.d.ts

@@ -3,7 +3,7 @@ import type { number_usd } from '../../types/typeAliases';
 /**
  * List of available Google models with descriptions
  *
- * Note: Synced with official API docs at 2025-08-20
+ * Note: Synced with official API docs at 2025-11-19
  *
  * @see https://ai.google.dev/models/gemini
  * @public exported from `@promptbook/google`

package/esm/typings/src/llm-providers/openai/openai-models.d.ts

@@ -2,7 +2,7 @@ import type { AvailableModel } from '../../execution/AvailableModel';
 /**
  * List of available OpenAI models with pricing
  *
- * Note: Synced with official API docs at 2025-08-20
+ * Note: Synced with official API docs at 2025-11-19
  *
  * @see https://platform.openai.com/docs/models/
  * @see https://openai.com/api/pricing/

package/esm/typings/src/remote-server/startAgentServer.d.ts

@@ -21,3 +21,6 @@ type AgentsServerOptions = {
  */
 export declare function startAgentServer(options: AgentsServerOptions): Promise<TODO_any>;
 export {};
+/**
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/esm/typings/src/remote-server/startRemoteServer.d.ts

@@ -25,4 +25,5 @@ export declare function startRemoteServer<TCustomOptions = undefined>(options: R
  * TODO: [🃏] Pass here some security token to prevent malitious usage and/or DDoS
  * TODO: [0] Set unavailable models as undefined in `RemoteLlmExecutionTools` NOT throw error here
  * TODO: Allow to constrain anonymous mode for specific models / providers
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
  */

package/esm/typings/src/types/typeAliases.d.ts

@@ -142,6 +142,12 @@ export type string_title = string;
  * For example `"My AI Assistant"`
  */
 export type string_agent_name = string;
+/**
+ * Semantic helper
+ *
+ * For example `"My AI Assistant"`
+ */
+export type string_agent_name_in_book = string;
 /**
  * Unstructured description of the persona
  *
@@ -530,7 +536,19 @@ export type string_dirname = string_absolute_dirname | string_relative_dirname;
  *
  * For example `"John Smith"`
  */
-export type string_person_fullname = string;
+export type string_person_fullname = `${string_person_firstname} ${string_person_lastname}` | string;
+/**
+ * Semantic helper
+ *
+ * For example `"John Smith"`
+ */
+export type string_person_firstname = string;
+/**
+ * Semantic helper
+ *
+ * For example `"John Smith"`
+ */
+export type string_person_lastname = string;
 /**
  * Semantic helper
  * Full profile of the person with his email and web (like in package.json)

package/esm/typings/src/utils/color/$randomColor.d.ts

@@ -8,4 +8,5 @@ export declare function $randomColor(): Color;
 /**
  * TODO: !! Use Internally Color.fromValues
  * TODO: !! randomColorWithAlpha
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
  */

package/esm/typings/src/utils/random/$generateBookBoilerplate.d.ts

@@ -1,14 +1,14 @@
 import type { PartialDeep } from 'type-fest';
 import type { AgentBasicInformation } from '../../book-2.0/agent-source/AgentBasicInformation';
 import { string_book } from '../../book-2.0/agent-source/string_book';
-import { string_agent_name } from '../../types/typeAliases';
+import { string_agent_name_in_book } from '../../types/typeAliases';
 type GenerateBookBoilerplateOptions = PartialDeep<Omit<AgentBasicInformation, 'parameters'>> & {
     /**
      * Name of the parent agent to inherit from
      *
      * @default 'Adam'
      */
-    parentAgentName?: string_agent_name;
+    parentAgentName?: string_agent_name_in_book;
 };
 /**
  * Generates boilerplate for a new agent book
@@ -20,3 +20,6 @@ type GenerateBookBoilerplateOptions = PartialDeep<Omit<AgentBasicInformation, 'p
  */
 export declare function $generateBookBoilerplate(options?: GenerateBookBoilerplateOptions): string_book;
 export {};
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */

package/esm/typings/src/utils/random/$randomAgentPersona.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @@@@
+ *
+ * @private internal helper function
+ */
+export declare function $randomAgentPersona(): string;
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */

package/esm/typings/src/utils/random/$randomFullnameWithColor.d.ts

@@ -0,0 +1,13 @@
+import { string_color, string_person_fullname } from '../../types/typeAliases';
+export type RandomFullnameWithColorResult = {
+    fullname: string_person_fullname;
+    color: string_color;
+};
+/**
+ *
+ * @private internal helper function
+ */
+export declare function $randomFullnameWithColor(): RandomFullnameWithColorResult;
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */

package/esm/typings/src/utils/random/$randomItem.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pick random item from the received array
+ *
+ * @private internal helper function
+ */
+export declare function $randomItem<TItem>(...items: Array<TItem>): TItem;
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */ 

package/esm/typings/src/utils/random/$randomSeed.d.ts

@@ -8,3 +8,6 @@ import type { number_seed } from '../../types/typeAliases';
  * @private internal helper function
  */
 export declare function $randomSeed(): number_seed;
+/**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+ */ 

package/esm/typings/src/utils/random/$randomToken.d.ts

@@ -10,5 +10,6 @@ import type { string_token } from '../../types/typeAliases';
  */
 export declare function $randomToken(randomness: number): string_token;
 /**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
  * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
  */

package/esm/typings/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.103.0-42`).
+ * It follows semantic versioning (e.g., `0.103.0-44`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/openai",
-    "version": "0.103.0-43",
+    "version": "0.103.0-45",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,
@@ -102,7 +102,7 @@
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/openai.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.103.0-43"
+        "@promptbook/core": "0.103.0-45"
     },
     "dependencies": {
         "bottleneck": "2.19.5",

package/umd/index.umd.js

@@ -18,14 +18,14 @@
      * @generated
      * @see https://github.com/webgptorg/book
      */
-    const BOOK_LANGUAGE_VERSION = '1.0.0';
+    const BOOK_LANGUAGE_VERSION = '2.0.0';
     /**
      * The version of the Promptbook engine
      *
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.103.0-43';
+    const PROMPTBOOK_ENGINE_VERSION = '0.103.0-45';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -120,6 +120,7 @@
         return crypto.randomBytes(randomness).toString('hex');
     }
     /**
+     * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
      * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
      */
 
@@ -2174,7 +2175,7 @@
     /**
      * List of available OpenAI models with pricing
      *
-     * Note: Synced with official API docs at 2025-08-20
+     * Note: Synced with official API docs at 2025-11-19
      *
      * @see https://platform.openai.com/docs/models/
      * @see https://openai.com/api/pricing/
@@ -2184,11 +2185,21 @@
         name: 'OPENAI_MODELS',
         value: [
             /**/
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'gpt-5.1',
+                modelName: 'gpt-5.1',
+                modelDescription: 'The best model for coding and agentic tasks with configurable reasoning effort.',
+                pricing: {
+                    prompt: pricing(`$1.25 / 1M tokens`),
+                    output: pricing(`$10.00 / 1M tokens`),
+                },
+            },
             {
                 modelVariant: 'CHAT',
                 modelTitle: 'gpt-5',
                 modelName: 'gpt-5',
-                modelDescription: "OpenAI's most advanced language model with unprecedented reasoning capabilities and 200K context window. Features revolutionary improvements in complex problem-solving, scientific reasoning, and creative tasks. Demonstrates human-level performance across diverse domains with enhanced safety measures and alignment. Represents the next generation of AI with superior understanding, nuanced responses, and advanced multimodal capabilities.",
+                modelDescription: "OpenAI's most advanced language model with unprecedented reasoning capabilities and 200K context window. Features revolutionary improvements in complex problem-solving, scientific reasoning, and creative tasks. Demonstrates human-level performance across diverse domains with enhanced safety measures and alignment. Represents the next generation of AI with superior understanding, nuanced responses, and advanced multimodal capabilities. DEPRECATED: Use gpt-5.1 instead.",
                 pricing: {
                     prompt: pricing(`$1.25 / 1M tokens`),
                     output: pricing(`$10.00 / 1M tokens`),
@@ -3749,11 +3760,11 @@
             if (!this.isCreatingNewAssistantsAllowed) {
                 throw new NotAllowed(`Creating new assistants is not allowed. Set \`isCreatingNewAssistantsAllowed: true\` in options to enable this feature.`);
             }
-            await this.playground();
+            // await this.playground();
             const { name, instructions } = options;
             const client = await this.getClient();
-            /*
-            TODO: !!!
+            /*/
+            //TODO: !!!
             async function downloadFile(url: string, folder = './tmp'): Promise<string> {
                 const filename = path.basename(url.split('?')[0]);
                 const filepath = path.join(folder, filename);
@@ -3797,8 +3808,8 @@
                 const file = await uploadFileToOpenAI(filepath);
                 uploadedFiles.push(file.id);
             }
-            */
-            alert('!!!! Creating new OpenAI assistant');
+            /**/
+            // alert('!!!! Creating new OpenAI assistant');
             // 3️⃣ Create assistant with uploaded files
             const assistant = await client.beta.assistants.create({
                 name,
@@ -3934,6 +3945,9 @@
             Object.setPrototypeOf(this, DatabaseError.prototype);
         }
     }
+    /**
+     * TODO: !!!! Explain that NotFoundError (!!! and other specific errors) has priority over DatabaseError in some contexts
+     */
 
     /**
      * This error type indicates that you try to use a feature that is not available in the current environment