docs: add support for embedding code snippets

Ref: #64
Signed-off-by: Tomas Dvorak <toomas2d@gmail.com>

.github/workflows/main.yml

@@ -34,6 +34,8 @@ jobs:
         run: yarn format
       - name: Commits Lint
         run: yarn commitlint  --verbose --from "${{ github.event.pull_request.base.sha || github.event.commits[0].id }}" --to "${{ github.event.pull_request.head.sha || github.event.head_commit.id }}"
+      - name: Documentation - code snippet embeddings
+        run: yarn docs:check
       - name: Build
         run: yarn build
       - name: Unit Tests

.husky/pre-commit

@@ -1,2 +1,2 @@
 yarn lint-staged
-CI=true yarn lint && yarn format && yarn ts:check && yarn run test:unit && yarn copyright
+CI=true yarn docs:check && yarn lint && yarn format && yarn ts:check && yarn run test:unit && yarn copyright

.release-it.json

@@ -18,7 +18,7 @@
     "publish": true
   },
   "hooks": {
-    "before:init": ["yarn lint", "yarn ts:check", "yarn test:all"],
+    "before:init": ["yarn docs:check", "yarn lint", "yarn ts:check", "yarn test:all"],
     "after:bump": ["yarn build"]
   },
   "github": {

README.md

@@ -41,7 +41,7 @@ yarn add bee-agent-framework
 
 ### Example
 
-```typescript
+```ts
 import { BeeAgent } from "bee-agent-framework/agents/bee/agent";
 import { OllamaChatLLM } from "bee-agent-framework/adapters/ollama/chat";
 import { TokenMemory } from "bee-agent-framework/memory/tokenMemory";

docs/agents.md

@@ -46,7 +46,7 @@ For more complex tasks, the agent may do way more iterations.
 
 In the following example, we will transform the knowledge gained into code.
 
-```typescript
+```ts
 const response = await agent
   .run({ prompt: "What is the current weather in Las Vegas?" })
   .observe((emitter) => {
@@ -78,7 +78,7 @@ You can alter the agent's behavior in the following ways.
 
 #### Setting execution policy
 
-```typescript
+```ts
 await agent.run(
   { prompt: "What is the current weather in Las Vegas?" },
 

docs/overview.md

@@ -25,7 +25,7 @@ The source directory (`src`) provides numerous modules that one can use.
 
 An emitter is a core functionality of the framework that gives you the ability to see what is happening under the hood. Because the vast majority of the frameworks components uses it, you can easily observe them.
 
-```typescript
+```ts
 import { Emitter, EventMeta } from "@/emitter/emitter.js";
 
 Emitter.root.match("*.*", (data: unknown, event: EventMeta) => {
@@ -146,7 +146,7 @@ The primary purpose of a logger is to provide developers and system administrato
 
 Every component within the framework uses the `Logger` class either by directly creating an instance of it or because it is being passed from the creator.
 
-```typescript
+```ts
 import { Logger, LoggerLevel } from "bee-agent-framework/logger";
 
 Logger.defaults.pretty = true; // (override default settings)

docs/tools.md

@@ -22,7 +22,7 @@ Tools MUST do the following:
 
   - `ToolRunOptions` is optional (default BaseToolRunOptions), optional parameters that are passed to the run method
 
-  ```typescript
+  ```ts
   import {
     BaseToolOptions,
     BaseToolRunOptions,
@@ -42,7 +42,7 @@ Tools MUST do the following:
 
   Note: Convention and best practice is to set the tool's name to the name of its class
 
-  ```typescript
+  ```ts
   name = "MyNewTool";
   ```
 
@@ -51,7 +51,7 @@ Tools MUST do the following:
   ❗Important: this description is used by the agent to determine when the tool should be used. It's probably the most important aspect of your tool and you should experiment with different natural language descriptions to ensure the tool is used in the correct circumstances. You can also include usage tips and guidance for the agent in the description, but
   its advisable to keep the description succinct in order to reduce the probability of conflicting with other tools, or adversely affecting agent behavior.
 
-  ```typescript
+  ```ts
   description = "Takes X action when given Y input resulting in Z output";
   ```
 
@@ -61,7 +61,7 @@ Tools MUST do the following:
 
   <!-- eslint-skip -->
 
-  ```typescript
+  ```ts
   inputSchema() {
       // any Zod definition is good here, this is typical simple example
       return z.object({
@@ -82,7 +82,7 @@ Tools MUST do the following:
 
   <!-- eslint-skip -->
 
-  ```typescript
+  ```ts
   static {
       this.register();
   }
@@ -92,7 +92,7 @@ Tools MUST do the following:
 
   <!-- eslint-skip -->
 
-  ```typescript
+  ```ts
   protected async _run(input: ToolInput<this>, options: BaseToolRunOptions | undefined, run: RunContext<this>) {
       // insert custom code here
       // MUST: return an instance of the output type specified in the tool class definition
@@ -104,7 +104,7 @@ Tools MUST do the following:
 
 In order for a tool to be of some utility within an agent, you must enable the agent with knowledge of the tool. To do this, the tool code module must be imported into the agent and passed to the tools array during creation of a `BeeAgent`. An example can be found in the [bee agent](../examples/agents/bee.ts) or you can use a code snippet such as the one below that creates an agent with the built-in [ArXiv tool](../src/tools/arxiv.ts):
 
-```typescript
+```ts
 import { ArXivTool } from "bee-agent-framework/tools/arxiv";
 
 const llm = new OllamaChatLLM({

package.json

@@ -65,6 +65,8 @@
     "infra:start-code-interpreter": "yarn _docker compose up bee-code-interpreter-k3s --detach --wait",
     "infra:stop-all": "yarn _docker compose down",
     "infra:clean-all": "yarn _docker compose down --volumes",
+    "docs:build": "embedme --source-root=. docs/**/*.md",
+    "docs:check": "yarn docs:build --verify",
     "lint": "yarn eslint",
     "lint:fix": "yarn eslint --fix",
     "format": "yarn prettier --check .",
@@ -153,6 +155,7 @@
     "@types/object-hash": "^3.0.6",
     "@types/turndown": "^5.0.5",
     "dotenv": "^16.4.5",
+    "embedme": "^1.22.1",
     "eslint": "^9.9.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-unused-imports": "^4.1.3",

yarn.lock

@@ -2774,6 +2774,7 @@ __metadata:
     dirty-json: "npm:0.9.2"
     dotenv: "npm:^16.4.5"
     duck-duck-scrape: "npm:^2.2.5"
+    embedme: "npm:^1.22.1"
     eslint: "npm:^9.9.0"
     eslint-config-prettier: "npm:^9.1.0"
     eslint-plugin-unused-imports: "npm:^4.1.3"
@@ -3126,6 +3127,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"chalk@npm:3.0.0":
+  version: 3.0.0
+  resolution: "chalk@npm:3.0.0"
+  dependencies:
+    ansi-styles: "npm:^4.1.0"
+    supports-color: "npm:^7.1.0"
+  checksum: 10c0/ee650b0a065b3d7a6fda258e75d3a86fc8e4effa55871da730a9e42ccb035bf5fd203525e5a1ef45ec2582ecc4f65b47eb11357c526b84dd29a14fb162c414d2
+  languageName: node
+  linkType: hard
+
 "chalk@npm:5.3.0, chalk@npm:^5.2.0, chalk@npm:^5.3.0, chalk@npm:~5.3.0":
   version: 5.3.0
   resolution: "chalk@npm:5.3.0"
@@ -3371,6 +3382,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"commander@npm:5.1.0":
+  version: 5.1.0
+  resolution: "commander@npm:5.1.0"
+  checksum: 10c0/da9d71dbe4ce039faf1fe9eac3771dca8c11d66963341f62602f7b66e36d2a3f8883407af4f9a37b1db1a55c59c0c1325f186425764c2e963dc1d67aec2a4b6d
+  languageName: node
+  linkType: hard
+
 "commander@npm:^10.0.1":
   version: 10.0.1
   resolution: "commander@npm:10.0.1"
@@ -3979,6 +3997,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"embedme@npm:^1.22.1":
+  version: 1.22.1
+  resolution: "embedme@npm:1.22.1"
+  dependencies:
+    chalk: "npm:3.0.0"
+    commander: "npm:5.1.0"
+    gitignore-parser: "npm:~0.0.2"
+    glob: "npm:~7.1.4"
+  bin:
+    embedme: dist/embedme.js
+  checksum: 10c0/d3c7373a8351599db9efc659781b28d2be44c41d670162482e2556ad1230f4d6db93188d9c751ade522531a41f260081059a6b2a32da3e20cf4cad55b95cf157
+  languageName: node
+  linkType: hard
+
 "emoji-regex@npm:^10.3.0":
   version: 10.3.0
   resolution: "emoji-regex@npm:10.3.0"
@@ -5042,6 +5074,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"gitignore-parser@npm:~0.0.2":
+  version: 0.0.2
+  resolution: "gitignore-parser@npm:0.0.2"
+  checksum: 10c0/ad2202f42b00aa6477b0c421c1916c655b6cdd595d05f34d128a7186523f539f22616c9ade34605749e91dafe64b1e13b87b3c556acf15a21c55e94772f0df3d
+  languageName: node
+  linkType: hard
+
 "glob-parent@npm:^5.1.2, glob-parent@npm:~5.1.2":
   version: 5.1.2
   resolution: "glob-parent@npm:5.1.2"
@@ -5106,6 +5145,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"glob@npm:~7.1.4":
+  version: 7.1.7
+  resolution: "glob@npm:7.1.7"
+  dependencies:
+    fs.realpath: "npm:^1.0.0"
+    inflight: "npm:^1.0.4"
+    inherits: "npm:2"
+    minimatch: "npm:^3.0.4"
+    once: "npm:^1.3.0"
+    path-is-absolute: "npm:^1.0.0"
+  checksum: 10c0/173245e6f9ccf904309eb7ef4a44a11f3bf68e9e341dff5a28b5db0dd7123b7506daf41497f3437a0710f57198187b758c2351eeaabce4d16935e956920da6a4
+  languageName: node
+  linkType: hard
+
 "global-directory@npm:^4.0.1":
   version: 4.0.1
   resolution: "global-directory@npm:4.0.1"
@@ -7298,7 +7351,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"minimatch@npm:^3.1.1, minimatch@npm:^3.1.2":
+"minimatch@npm:^3.0.4, minimatch@npm:^3.1.1, minimatch@npm:^3.1.2":
   version: 3.1.2
   resolution: "minimatch@npm:3.1.2"
   dependencies: