From 144d7d2eab2cba8afa328aa387a638148a45e720 Mon Sep 17 00:00:00 2001 From: Ismael Faro Date: Mon, 2 Dec 2024 23:42:03 -0500 Subject: [PATCH] docs: fix markdown block type and updating the modules in main README --- README.md | 31 +++++++++++++++---------------- docs/cache.md | 10 +++++----- docs/dev_tools.md | 2 +- docs/emitter.md | 35 +++++++++++++++++++++-------------- docs/errors.md | 3 +++ docs/logger.md | 15 ++++++++++----- 6 files changed, 55 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index d89ba3de..e72fe02a 100644 --- a/README.md +++ b/README.md @@ -101,25 +101,24 @@ console.log(`Agent 🤖 : `, response.result.text); ➡️ To run an arbitrary example, use the following command `yarn start examples/agents/bee.ts` (just pass the appropriate path to the desired example). -### 📦 Modules +### 📦 Bee Framework Modules The source directory (`src`) provides numerous modules that one can use. -| Name | Description | -| ------------------------------------------------ | ------------------------------------------------------------------------------------------- | -| [**agents**](/docs/agents.md) | Base classes defining the common interface for agent. | -| [**llms**](/docs/llms.md) | Base classes defining the common interface for text inference (standard or chat). | -| [**template**](/docs/templates.md) | Prompt Templating system based on `Mustache` with various improvements. | -| [**memory**](/docs/memory.md) | Various types of memories to use with agent. | -| [**tools**](/docs/tools.md) | Tools that an agent can use. | -| [**cache**](/docs/cache.md) | Preset of different caching approaches that can be used together with tools. | -| [**errors**](/docs/errors.md) | Error classes and helpers to catch errors fast. | -| [**adapters**](/docs/llms.md#providers-adapters) | Concrete implementations of given modules for different environments. | -| [**logger**](/docs/logger.md) | Core component for logging all actions within the framework. | -| [**serializer**](/docs/serialization.md) | Core component for the ability to serialize/deserialize modules into the serialized format. | -| [**version**](/docs/version.md) | Constants representing the framework (e.g., latest version) | -| [**emitter**](/docs/emitter.md) | Bringing visibility to the system by emitting events. | -| **internals** | Modules used by other modules within the framework. | +- [**Agents**](/docs/agents.md) : Base classes defining the common interface for agent. + - [**LLM**](/docs/llms.md) : Base classes defining the common interface for text inference (standard or chat) + - [**Template Prompt**](/docs/templates.md): Templating system based on Mustache with various improvements. + - [**Adapters**](/docs/llms.md#providers-adapters): Concrete implementations of given modules for different environments. + - [**Memory**](/docs/memory.md) : Various types of memories to use with agent. + - [**Cache**](/docs/cache.md): Preset of different caching approaches that can be used together with tools. + - [**Tools**](/docs/tools.md) : Tools that an agent can use. + - Dev tool: + - [**emitter**](/docs/emitter.md) : Bringing visibility to the system by emitting events. + - [**logger**](/docs/logger.md) : Core component for logging all actions within the framework. + - [**serializer**](/docs/serialization.md) : Core component for the ability to serialize/deserialize modules. + - [**errors**](/docs/errors.md) : Error classes and helpers to catch errors fast. +- [**version**](/docs/version.md) : Constants representing the framework (e.g., latest version) +- **internals** : Modules used by other modules within the framework. | To see more in-depth explanation see [overview](/docs/overview.md). diff --git a/docs/cache.md b/docs/cache.md index 24d20b99..5f2872a3 100644 --- a/docs/cache.md +++ b/docs/cache.md @@ -105,13 +105,13 @@ Persists cache data to the filesystem. ```ts import { FileCache } from "bee-agent-framework/cache/fileCache"; +import * as os from "node:os"; -const cache = new FileCache({ - fullPath: "/path/to/cache.json", +const cache = new FileCache({ + fullPath: `${os.tmpdir()}/bee_file_cache_${Date.now()}.json`, }); - -await cache.set("user:123", userData); -// Data is automatically persisted to disk +console.log(`Saving cache to "${cache.source}"`); +await cache.set("abc", { firstName: "John", lastName: "Doe" }); ``` _Source: [examples/cache/fileCache.ts](/examples/cache/fileCache.ts)_ diff --git a/docs/dev_tools.md b/docs/dev_tools.md index b7c734be..9422661d 100644 --- a/docs/dev_tools.md +++ b/docs/dev_tools.md @@ -137,7 +137,7 @@ Key features: The development tools can be configured through environment variables: -```bash +```shell # Logging export BEE_FRAMEWORK_LOG_LEVEL=debug export BEE_FRAMEWORK_LOG_PRETTY=true diff --git a/docs/emitter.md b/docs/emitter.md index dae351b1..c5ce1fa3 100644 --- a/docs/emitter.md +++ b/docs/emitter.md @@ -107,27 +107,34 @@ Registers a listener with advanced matching capabilities. ```ts -import { Emitter } from "bee-agent-framework/emitter/emitter"; +import { Callback, Emitter } from "bee-agent-framework/emitter/emitter"; +import { BaseLLM } from "bee-agent-framework/llms/base"; -const emitter = new Emitter({ namespace: ["app"] }); +interface Events { + update: Callback<{ data: string }>; +} -// Match all events in namespace -emitter.match("*.*", (data, event) => { - console.log(`${event.path}: ${JSON.stringify(data)}`); +const emitter = new Emitter({ + namespace: ["app"], }); -// Match with regular expression -emitter.match(/error/, (data, event) => { - console.log(`Error event: ${event.name}`); -}); +// Match events by a concrete name (strictly typed) +emitter.on("update", async (data, event) => {}); + +// Match all events emitted directly on the instance (not nested) +emitter.match("*", async (data, event) => {}); -// Match with custom function +// Match all events (included nested) +emitter.match("*.*", async (data, event) => {}); + +// Match events by providing a filter function emitter.match( - (event) => event.context.priority === "high", - (data, event) => { - console.log(`High priority event: ${event.name}`); - }, + (event) => event.creator instanceof BaseLLM, + async (data, event) => {}, ); + +// Match events by regex +emitter.match(/watsonx/, async (data, event) => {}); ``` _Source: [examples/emitter/matchers.ts](/examples/emitter/matchers.ts)_ diff --git a/docs/errors.md b/docs/errors.md index 105d1fb2..bd334321 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -113,6 +113,9 @@ const error = new FrameworkError( console.log("Message", error.message); // Main error message console.log("Meta", { fatal: error.isFatal, retryable: error.isRetryable }); // Is the error fatal/retryable? console.log("Context", error.context); // Context in which the error occurred +console.log(error.explain()); // Human-readable format without stack traces (ideal for LLMs) +console.log(error.dump()); // Full error dump, including sub-errors +console.log(error.getCause()); // Retrieve the initial cause of the error ``` _Source: [examples/errors/base.ts](/examples/errors/base.ts)_ diff --git a/docs/logger.md b/docs/logger.md index bc0c0727..1bed73e9 100644 --- a/docs/logger.md +++ b/docs/logger.md @@ -96,11 +96,16 @@ Logger.defaults.level = LoggerLevel.TRACE; // Set log level to trace (default: T Logger.defaults.name = undefined; // Optional name for logger (default: undefined) Logger.defaults.bindings = {}; // Optional bindings for structured logging (default: empty) -const parentLogger = Logger.root.child({ name: "app" }); -const moduleLogger = parentLogger.child({ - name: "module", - level: "debug", -}); +// Create a child logger for your app +const logger = Logger.root.child({ name: "app" }); + +// Log at different levels +logger.trace("Trace!"); +logger.debug("Debug!"); +logger.info("Info!"); +logger.warn("Warning!"); +logger.error("Error!"); +logger.fatal("Fatal!"); ``` #### Logging Methods