chore(release): v0.0.0-alpha.0

Author: MichielvdVelde

.github/workflows/ci.yaml

@@ -0,0 +1,31 @@
+name: Code Coverage
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  nodejs:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x,20.x]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    - name: Set up Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run the tests
+      run: npm run test:coverage

.gitignore

@@ -0,0 +1,6 @@
+dist
+node_modules
+*.tsbuildinfo
+.coverage
+types
+browser

LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2023 We Can Do Better
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,96 @@
+# 🏛️ Delphi
+
+Delphi is a versatile and adaptable conversational agent framework that
+streamlines the creation and management of chatbots and AI-driven communication
+systems. Its design prioritizes abstraction and provider-independence, allowing
+for seamless integration with various message providers. Delphi is compatible
+with a range of environments, including browsers, Node.js, and Deno, making it
+an ideal choice for diverse application scenarios.
+
+## 🚀 Features
+
+- 🤖 **Provider-Independent Messaging:** Delphi abstracts the messaging
+  function, allowing seamless integration with various providers like OpenAI and
+  Azure OpenAI.
+- 🔄 **Flexible Conversational Flow:** Manages complex conversation patterns
+  with ease, facilitating intelligent and context-aware interactions.
+- 🛠️ **Customizable Agent Options:** Tailor your agent with configurable settings
+  such as maximum rounds and specific model preferences.
+- 🌍 **Cross-Platform Compatibility:** Works effortlessly in browsers, Node.js,
+  and Deno environments.
+- 📚 **Context Management:** Efficiently maintains conversation states,
+  enhancing the continuity and relevance of interactions.
+- 📝 **Robust Schema Validation:** Ensures the integrity and correctness of data
+  with JSON schema validation.
+- 🎛️ **Modular Design:** Facilitates easy integration and scalability through a
+  clear and modular code structure.
+
+## 📌 Requirements
+
+- Node.js (v18 or newer), a modern browser, or Deno
+- TypeScript
+- An account with a supported message provider (e.g., Azure, OpenAI)
+
+## 🛠️ Installation
+
+Delphi is available on npm and can be easily installed:
+
+```bash
+npm install @wecandobetter/delphi
+```
+
+## 🚀 Getting Started
+
+To quickly get started with Delphi:
+
+1. **Import Delphi:** Import the necessary components from Delphi in your
+   project.
+   ```typescript
+   import { Agent, Context } from "@wecandobetter/delphi";
+   ```
+
+2. **Create an Agent:** Instantiate an `Agent` with your desired configuration.
+   ```typescript
+   const agent = new Agent("myAgent" /* ... configuration ... */);
+   ```
+
+3. **Initialize Context:** Set up a `Context` to manage the conversation state.
+   ```typescript
+   const context = new Context();
+
+   context.addMessage({
+     role: "system",
+     content: "You are a helpful assistant!",
+   });
+   ```
+
+4. **Run the Agent:** Start the agent with the initialized context.
+   ```typescript
+   const message = await agent.run(context);
+   console.log(message.content);
+   ```
+
+This example gives you a basic setup for initiating a conversation with Delphi.
+For more detailed usage and advanced features, refer to the documentation.
+
+## 📖 Documentation
+
+Visit our [Documentation Page](./docs) for information on API usage and advanced
+features.
+
+## 🤝 Contributing
+
+Contributions are welcome! Create an issue, open a pull request, or reach out to
+us in the discussions section.
+
+## 📜 License
+
+Delphi is released under the MIT License. See the [LICENSE](LICENSE) file for
+more details.
+
+## ✉️ Contact
+
+Reach out to us at [contact@wcdb.life](mailto:contact@wcdb.life) for support or
+inquiries.
+
+Happy coding! 🎉

docs/agent_functions.md

@@ -0,0 +1,74 @@
+# 📘 Delphi Tutorial: Using Agent Functions
+
+In Delphi, agent functions are a versatile tool allowing your conversational
+agent to execute specific tasks, like data retrieval or complex computations,
+dynamically during a conversation. Let's dive into how you can utilize these
+functions in your Delphi projects.
+
+## Step 1: Setting Up Your Environment
+
+Before beginning, ensure you have Delphi and its dependencies installed in your
+project. If you haven't already set up Delphi, refer to the 'Getting Started'
+section of the Delphi README.
+
+## Step 2: Define an Agent Function
+
+An agent function in Delphi takes an input, performs an operation, and returns
+an output. To define one:
+
+1. **Create a New Function Class**: Define a new class for your function.
+
+2. **Specify Input Schema**: Define a JSON schema for the input. This schema is
+   used to validate the data your function will receive.
+
+3. **Implement the Function Logic**: Write the core logic of your function in
+   the constructor.
+
+Example:
+
+```typescript
+import { AgentFunction, type JSONSchemaType } from "@wecandobetter/delphi";
+
+interface ExampleInput {
+  query: string;
+}
+
+const exampleInputSchema: JSONSchemaType<ExampleInput> = {
+  type: "object",
+  properties: {
+    query: { type: "string" },
+  },
+  required: ["query"],
+};
+
+const exampleFunction = new AgentFunction<ExampleInput, string>(
+  "exampleFunction",
+  "This is an example function",
+  exampleInputSchema,
+  async ({ query }) => {
+    // Your function logic here, returning a string
+    return `You queried: ${query}`;
+  },
+);
+```
+
+## Step 3: Register and Enable the Function
+
+With your function defined, the next step is to register it with your agent's
+context and enable it.
+
+```typescript
+const context = new Context();
+
+context.addFunction(exampleFunction);
+context.functions.enable(exampleFunction.name);
+```
+
+## Conclusion
+
+Agent functions in Delphi provide a powerful way to extend the capabilities of
+your conversational agents. By defining custom functions, registering them with
+your agent, and then utilizing them in conversation flows, you can create rich,
+interactive, and dynamic conversational experiences. The key is to tailor these
+functions to fit the specific needs and contexts of your application. Happy
+coding!

docs/agents/wikipedia.md

@@ -0,0 +1,147 @@
+# 📘 Delphi Tutorial: Creating a Wikipedia Search Agent
+
+In this tutorial, we'll guide you through creating a conversational agent using
+Delphi that can perform Wikipedia searches. This agent will leverage the Azure
+OpenAI client for communication and a custom agent function for searching
+Wikipedia.
+
+## 📚 Prerequisites
+
+- Ensure you have Node.js installed.
+- Set up a project with TypeScript.
+- Install the `@azure/openai` and `wikipedia` npm packages.
+
+## Step 1: Import Dependencies
+
+First, import all the necessary modules at the top of your TypeScript file:
+
+```typescript
+import { OpenAIClient, OpenAIKeyCredential } from "@azure/openai";
+import wikipedia from "wikipedia";
+
+import {
+  Agent,
+  AgentFunction,
+  Context,
+  type JSONSchemaType,
+} from "@wecandobetter/delphi";
+```
+
+## Step 2: Define Search Parameters and Results
+
+Define interfaces for your search parameters and the expected search results:
+
+```typescript
+interface SearchParameters {
+  query: string;
+  limit?: number;
+  suggestion?: boolean;
+}
+
+interface SearchResult {
+  results: string[];
+  suggestion?: string;
+}
+```
+
+## Step 3: Create a JSON Schema
+
+Define a JSON schema for validating the input to your search function:
+
+```typescript
+const searchSchema: JSONSchemaType<SearchParameters> = {
+  type: "object",
+  properties: {
+    query: { type: "string" },
+    limit: { type: "number", nullable: true },
+    suggestion: { type: "boolean", nullable: true },
+  },
+  required: ["query"],
+  additionalProperties: false,
+};
+```
+
+## Step 4: Implement the Search Function
+
+Create an instance of `AgentFunction` that performs the Wikipedia search:
+
+```typescript
+const searchFn = new AgentFunction<SearchParameters, SearchResult>(
+  "search",
+  "Search on Wikipedia",
+  searchSchema,
+  async ({ query, limit = 5, suggestion = true }) => {
+    const { results, suggestion: sugg } = await wikipedia.search(query, {
+      limit,
+      suggestion,
+    });
+    return { results: results.map(({ title }) => title), suggestion: sugg };
+  },
+);
+```
+
+## Step 5: Set Up the OpenAI Client
+
+Configure the OpenAI client with your API key:
+
+```typescript
+const client = new OpenAIClient(new OpenAIKeyCredential("<API_KEY>"));
+```
+
+## Step 6: Create the Agent
+
+Instantiate an `Agent` that will handle chat completions:
+
+```typescript
+const agent = new Agent(
+  "wiki",
+  async (messages, options) => {
+    const response = await client.getChatCompletions(
+      options.model,
+      messages,
+      options,
+    );
+    return response.choices[0].message!;
+  },
+  { client: { model: "gpt-4-1106-preview" } },
+);
+```
+
+## Step 7: Initialize the Context
+
+Create a new `Context` and add a system message to it:
+
+```typescript
+const context = new Context();
+context.addMessage({
+  role: "system",
+  content:
+    "Search Wikipedia for a random scientific subject and tell me about it.",
+});
+```
+
+## Step 8: Register and Enable the Function
+
+Register your search function in the context and enable it:
+
+```typescript
+context.functions.set(searchFn.name, searchFn);
+context.functions.enable(searchFn.name);
+```
+
+## Step 9: Run the Agent and Display the Result
+
+Finally, run the agent with the context and log the result:
+
+```typescript
+const result = await agent.run(context);
+console.log(result.content);
+```
+
+## 🎉 Conclusion
+
+Congratulations! You've successfully created a Delphi agent that can search
+Wikipedia based on user prompts and display the results. This tutorial showcases
+the integration of custom agent functions, use of external APIs, and
+conversation management in Delphi. Feel free to expand and customize your agent
+to suit your specific needs.