diff --git a/docs/docs/03-guides/01-first-tool.mdx b/docs/docs/03-guides/01-first-tool.mdx index 6f9498c4..6cb2f8f1 100644 --- a/docs/docs/03-guides/01-first-tool.mdx +++ b/docs/docs/03-guides/01-first-tool.mdx @@ -1,3 +1,7 @@ +--- +hide_table_of_contents: true +--- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -14,16 +18,16 @@ The following guides will show you how to write and package custom Tools in Pyth unleashing the full potential of your Agents by enabling them to integrate with any data source, service, or platform with just a few lines of code. - - - + + + - - + + - - + + \ No newline at end of file diff --git a/docs/snippets/go-hash-tool-readme.md.mdx b/docs/snippets/go-hash-tool-readme.md.mdx index 82162c71..3bf628a0 100644 --- a/docs/snippets/go-hash-tool-readme.md.mdx +++ b/docs/snippets/go-hash-tool-readme.md.mdx @@ -1,4 +1,4 @@ -## Writing your first tool in Go +## Writing your first tool in Go {#writing-your-first-tool-in-go-eb5bb8c4} [go-hash-tool](https://github.com/otto8-ai/go-hash-tool) contains a reference `Go` implementation of the `Hash` Tool. @@ -12,7 +12,7 @@ git clone git@github.com:otto8-ai/go-hash-tool
-## Tool Repo Structure +## Tool Repo Structure {#tool-repo-structure-eb5bb8c4} The directory tree below highlights the files required to implement `Hash` in Go and package it for `Otto8`. @@ -30,7 +30,7 @@ go-hash-tool
-## Defining the `Hash` Tool +## Defining the `Hash` Tool {#defining-the-hash-tool-eb5bb8c4} The `tool.gpt` file contains [GPTScript Tool Definitions](https://docs.gptscript.ai/tools/gpt-file-reference) which describe a set of Tools that can be used by Agents in `Otto8`. Every Tool repository must have a `tool.gpt` file in its root directory. @@ -89,7 +89,7 @@ Param: algo: The algorithm to generate a hash with. Default is "sha256". Support
-## Tool Metadata +## Tool Metadata {#tool-metadata-eb5bb8c4} The `tool.gpt` file also provides the following metadata for use in `Otto8`: @@ -150,7 +150,7 @@ https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-d
-## Implementing Business Logic +## Implementing Business Logic {#implementing-business-logic-eb5bb8c4} The `main.go` file is the entry point of the `gptscript-go-tool` binary that is executed by `Otto8` when the `Hash` Tool is called. @@ -202,7 +202,7 @@ The Body of the `Verify` Tool definition would then simply pass `verify` to `gpt ```yaml Name: Verify -# ... +# ... {#-eb5bb8c4} #!{GPTSCRIPT_TOOL_DIR}/bin/gptscript-go-tool verify ``` @@ -371,7 +371,7 @@ func keys[V any](m map[string]V) []string {
-## Testing `main.go` Locally +## Testing `main.go` Locally {#testing-main-go-locally-eb5bb8c4} Before adding a Tool to `Otto8`, verify that the Go business logic works on your machine. @@ -394,7 +394,7 @@ To do this, run through the following steps in the root of your local fork:
-## Adding The `Hash` Tool to `Otto8` +## Adding The `Hash` Tool to `Otto8` {#adding-the-hash-tool-to-otto8-eb5bb8c4} Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto8` by performing the steps below: @@ -432,7 +432,7 @@ Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto -## Using The `Hash` Tool in an Agent +## Using The `Hash` Tool in an Agent {#using-the-hash-tool-in-an-agent-eb5bb8c4} To use the `Hash` Tool in an Agent, open the Agent's Edit page, then: diff --git a/docs/snippets/node-hash-tool-readme.md.mdx b/docs/snippets/node-hash-tool-readme.md.mdx index 67edcead..ae3fecf6 100644 --- a/docs/snippets/node-hash-tool-readme.md.mdx +++ b/docs/snippets/node-hash-tool-readme.md.mdx @@ -1,4 +1,4 @@ -## Writing your first tool in Node.js (with Typescript) +## Writing your first tool in Node.js (with Typescript) {#writing-your-first-tool-in-node-js-with-typescript-aeed7f15} [node-hash-tool](https://github.com/otto8-ai/node-hash-tool) contains a reference Typescript `Node.js` implementation of the `Hash` Tool. @@ -11,7 +11,7 @@ git clone git@github.com:otto8-ai/node-hash-tool ```
-## Tool Repo Structure +## Tool Repo Structure {#tool-repo-structure-aeed7f15} The directory tree below highlights the files required to implement `Hash` in Typescript and package it for `Otto8`. @@ -31,7 +31,7 @@ node-hash-tool
-## Defining the `Hash` Tool +## Defining the `Hash` Tool {#defining-the-hash-tool-aeed7f15} The `tool.gpt` file contains [GPTScript Tool Definitions](https://docs.gptscript.ai/tools/gpt-file-reference) which describe a set of Tools that can be used by Agents in `Otto8`. Every Tool repository must have a `tool.gpt` file in its root directory. @@ -90,7 +90,7 @@ Param: algo: The algorithm to generate a hash with. Default is "sha256". Support
-## Tool Metadata +## Tool Metadata {#tool-metadata-aeed7f15} The `tool.gpt` file also provides the following metadata for use in `Otto8`: @@ -151,7 +151,7 @@ https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-d
-## Implementing Business Logic +## Implementing Business Logic {#implementing-business-logic-aeed7f15} As we saw earlier, the `npm` command invoked by the `Tool Body` passes `hash` as an argument to the `tool` script. @@ -226,7 +226,7 @@ And the Body of the `Verify` Tool would pass `verify` to the `tool` script inste ```yaml Name: Verify -# ... +# ... {#-aeed7f15} #!/usr/bin/env npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- verify ``` @@ -351,7 +351,7 @@ export function hash(data: string = '', algo = 'sha256'): string {
-## Testing `src/tools.ts` and `src/hash.ts` Locally +## Testing `src/tools.ts` and `src/hash.ts` Locally {#testing-src-tools-ts-and-src-hash-ts-locally-aeed7f15} Before adding a Tool to `Otto8`, verify that the Typescript business logic works on your machine. @@ -374,7 +374,7 @@ To do this, run through the following steps in the root of your local fork:
-## Adding The `Hash` Tool to `Otto8` +## Adding The `Hash` Tool to `Otto8` {#adding-the-hash-tool-to-otto8-aeed7f15} Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto8` by performing the steps below: @@ -412,7 +412,7 @@ Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto -## Using The `Hash` Tool in an Agent +## Using The `Hash` Tool in an Agent {#using-the-hash-tool-in-an-agent-aeed7f15} To use the `Hash` Tool in an Agent, open the Agent's Edit page, then: diff --git a/docs/snippets/python-hash-tool-readme.md.mdx b/docs/snippets/python-hash-tool-readme.md.mdx index 53b2b979..0f79505d 100644 --- a/docs/snippets/python-hash-tool-readme.md.mdx +++ b/docs/snippets/python-hash-tool-readme.md.mdx @@ -1,4 +1,4 @@ -## Writing your first tool in Python +## Writing your first tool in Python {#writing-your-first-tool-in-python-28572835} [python-hash-tool](https://github.com/otto8-ai/python-hash-tool) contains a reference `Python` implementation of the `Hash` Tool. @@ -12,7 +12,7 @@ git clone git@github.com:otto8-ai/python-hash-tool
-## Tool Repo Structure +## Tool Repo Structure {#tool-repo-structure-28572835} The directory tree below highlights the files required to implement `Hash` in Python and package it for `Otto8`. @@ -24,7 +24,7 @@ python-hash-tool ```
-## Defining the `Hash` Tool +## Defining the `Hash` Tool {#defining-the-hash-tool-28572835} The `tool.gpt` file contains [GPTScript Tool Definitions](https://docs.gptscript.ai/tools/gpt-file-reference) which describe a set of Tools that can be used by Agents in `Otto8`. Every Tool repository must have a `tool.gpt` file in its root directory. @@ -84,7 +84,7 @@ Param: algo: The algorithm to generate a hash with. Default is "sha256". Support
-## Tool Metadata +## Tool Metadata {#tool-metadata-28572835} The `tool.gpt` file also provides the following metadata for use in `Otto8`: @@ -144,7 +144,7 @@ https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-d
-## Implementing Business Logic +## Implementing Business Logic {#implementing-business-logic-28572835} The `hash.py` file executed by the `Tool Body` is the concrete implementation of the Tool's business logic. @@ -261,7 +261,7 @@ if __name__ == '__main__':
-## Testing `hash.py` Locally +## Testing `hash.py` Locally {#testing-hash-py-locally-28572835} Before adding a Tool to `Otto8`, verify that the Python business logic works on your machine. @@ -298,7 +298,7 @@ To do this, run through the following steps in the root of your local fork:
-## Adding The `Hash` Tool to `Otto8` +## Adding The `Hash` Tool to `Otto8` {#adding-the-hash-tool-to-otto8-28572835} Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto8` by performing the steps below: @@ -336,7 +336,7 @@ Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto -## Using The `Hash` Tool in an Agent +## Using The `Hash` Tool in an Agent {#using-the-hash-tool-in-an-agent-28572835} To use the `Hash` Tool in an Agent, open the Agent's Edit page, then: diff --git a/docs/src/plugins/fetch-snippets/index.ts b/docs/src/plugins/fetch-snippets/index.ts index 5f03b321..0a8889b0 100644 --- a/docs/src/plugins/fetch-snippets/index.ts +++ b/docs/src/plugins/fetch-snippets/index.ts @@ -1,16 +1,15 @@ import fs from 'fs'; import path from 'path'; import axios from 'axios'; +import crypto from 'crypto'; import { LoadContext, Plugin } from '@docusaurus/types'; -// Array of permalinks to raw files in different repositories const FILE_URLS = [ 'https://raw.githubusercontent.com/otto8-ai/python-hash-tool/main/README.md', 'https://raw.githubusercontent.com/otto8-ai/go-hash-tool/main/README.md', 'https://raw.githubusercontent.com/otto8-ai/node-hash-tool/main/README.md', ]; -// Mapping of file extensions to code block languages for syntax highlighting const EXTENSION_LANGUAGE_MAP: Record = { '.py': 'python', '.go': 'go', @@ -46,10 +45,13 @@ async function fetchFiles(outputDir: string) { const ext = path.extname(filePath); const language = EXTENSION_LANGUAGE_MAP[ext] || ''; // Default to plain text if extension is unknown - // Wrap content in a Markdown code block for supported file types let wrappedContent = data; - if (language != 'markdown') { + if (language !== 'markdown') { + // Wrap content in a Markdown code block for supported file types wrappedContent = language ? `\`\`\`${language}\n${data}\n\`\`\`` : data; + } else { + // Add unique and explicit IDs to all headers in Markdown content + wrappedContent = addUniqueHeaderIds(url, data); } const outputFilePath = path.join(outputDir, `${repoName}-${filePath}.mdx`); @@ -62,6 +64,25 @@ async function fetchFiles(outputDir: string) { ); } +// Function to add unique IDs to Markdown headers +function addUniqueHeaderIds(url, markdown: string): string { + const urlHash = crypto.createHash('sha256').update(url).digest('hex').substring(0, 8); + + let headerCounts: Record = {}; + return markdown.replace(/^(#{1,6})\s+(.+)$/gm, (match, hashes, title) => { + const slugBase = title.toLowerCase().replace(/[^\w]+/g, '-').replace(/^-|-$/g, ''); + const count = headerCounts[slugBase] || 0; + const uniqueSlug = count ? `${slugBase}-${urlHash}-${count}` : `${slugBase}-${urlHash}`; + headerCounts[slugBase] = count + 1; + + return `${hashes} ${title} {#${uniqueSlug}}`; + }); +} + +function getShortHash(input: string): string { + return crypto.createHash('sha256').update(input).digest('hex').substring(0, 8); +} + export default function pluginFetchSnippets(context: LoadContext): Plugin { return { name: 'fetch-snippets',