@j-o-r/hello-dave 0.0.7 → 0.0.8

package/docs/howtos/spawn-agents.md.bak

@@ -0,0 +1,200 @@
+# Spawning and Managing Agents
+
+This guide covers how to directly call agents, use the Spawn Dave workflow, and utilize Spawn Agent for creating, testing, and improving agents. It includes practical examples in Bash and JavaScript, as well as concepts for self-improvement loops. For foundational concepts on agent interactions, refer to [agent-networking.md](./agent-networking.md).
+
+## 1. Direct Agent Calls
+
+Direct agent calls allow you to invoke specific agents from the command line or scripts without spawning a full workflow. This is useful for quick queries or testing individual agent behaviors.
+
+### Real Project Example: Calling GPT Agent
+
+In the project, you can directly invoke the GPT agent using the provided script.
+
+**JavaScript Snippet (examples/gpt_agent.js):**
+```javascript
+// examples/gpt_agent.js
+const { createAgent } = require('../lib/agent-factory'); // Assuming agent factory module
+
+async function runAgent(query) {
+  const agent = createAgent('gpt'); // Initialize GPT agent
+  const response = await agent.process(query);
+  console.log(response);
+}
+
+if (require.main === module) {
+  const query = process.argv[2];
+  if (!query) {
+    console.error('Usage: node examples/gpt_agent.js "your query"');
+    process.exit(1);
+  }
+  runAgent(query).catch(console.error);
+}
+```
+
+**Bash Command to Run:**
+```bash
+node examples/gpt_agent.js "What is the capital of France?"
+# Output: Paris (or similar GPT response)
+```
+
+This is a real example from the project, enabling straightforward execution. Extend it by passing additional flags for configuration, e.g., `--model gpt-4`.
+
+## 2. Spawn Dave Workflow
+
+The Spawn Dave workflow (examples/spawn_dave.js) is a predefined sequence for initializing a "Dave" agent instance, which handles complex tasks like multi-step reasoning or integration with external tools.
+
+### Overview
+- **Purpose:** Spawn a Dave agent that can orchestrate sub-agents or workflows.
+- **Key Features:** Tool integration, state management, and logging.
+
+### Example: Running Spawn Dave
+
+**JavaScript Snippet (examples/spawn_dave.js):**
+```javascript
+// examples/spawn_dave.js
+const { spawnDave } = require('../workflows/spawn-dave'); // Import workflow
+
+async function main(task) {
+  const dave = await spawnDave({ 
+    tools: ['web_search', 'code_executor'], 
+    model: 'gpt-4' 
+  });
+  const outcome = await dave.execute(task);
+  console.log('Dave's response:', outcome);
+}
+
+if (require.main === module) {
+  const task = process.argv[2] || 'Default task: Analyze market trends.';
+  main(task).catch(console.error);
+}
+```
+
+**Bash Command:**
+```bash
+node examples/spawn_dave.js "Summarize recent AI advancements."
+```
+
+This workflow automatically handles agent lifecycle: spawn, execute, and cleanup. For networking multiple Daves, see [agent-networking.md](./agent-networking.md).
+
+## 3. Spawn Agent (examples/spawn_agent.js or agentDave)
+
+Spawn Agent is a utility for dynamically creating, testing, and improving agents based on outcomes. It's ideal for iterative development, where agents self-improve through workflows and tests. The entry point is `examples/spawn_agent.js`, which can be aliased as `agentDave` via the `package.json` scripts (e.g., `npm run agentDave -- create ...`).
+
+### Core Functionality
+- **Creating Agents:** Define agent specs (prompts, tools, models) and spawn instances.
+- **Testing:** Run predefined tests to evaluate performance.
+- **Improving:** Use feedback loops to refine prompts or configurations based on outcomes.
+- **Self-Improvement Loops:** Agents can analyze their own outputs and suggest updates.
+
+### Example: Basic Spawn and Test
+
+**Bash Usage (via examples/spawn_agent.js or npm run agentDave):**
+```bash
+# Spawn a new agent for math tasks
+node examples/spawn_agent.js create --name math-solver --tools calculator --prompt "Solve math problems step-by-step."
+
+# Or using alias
+npm run agentDave -- create --name math-solver --tools calculator --prompt "Solve math problems step-by-step."
+
+# Test the agent
+node examples/spawn_agent.js test --name math-solver --input "2+2*3" --expected 8
+
+# Improve based on outcomes
+node examples/spawn_agent.js improve --name math-solver --feedback "Failed on algebra; add quadratic formula."
+```
+
+**JavaScript Integration (Custom Script):**
+```javascript
+// test-spawn.js
+const { spawnAgent, testAgent, improveAgent } = require('../examples/spawn_agent');
+
+async function workflow() {
+  // Create
+  const agent = await spawnAgent({
+    name: 'researcher',
+    tools: ['web_search', 'browse_page'],
+    prompt: 'Conduct thorough research on topics.'
+  });
+
+  // Test
+  const testResult = await testAgent(agent, { query: 'Latest on quantum computing', expected: /qubits/ });
+  console.log('Test passed:', testResult.passed);
+
+  // Self-Improvement Loop
+  if (!testResult.passed) {
+    const improvements = await improveAgent(agent, testResult.feedback);
+    console.log('Suggested improvements:', improvements);
+    // Re-spawn with updates
+    const updatedAgent = await spawnAgent({ ...agent.config, prompt: improvements.newPrompt });
+  }
+}
+
+workflow().catch(console.error);
+```
+
+**Running the Script:**
+```bash
+node test-spawn.js
+```
+
+### Self-Improvement Loops
+Implement loops where agents evaluate their performance using tools like `test_agent.js` for testing and `memory_agent` for storing past evaluations and improvements.
+
+1. **Execute Task:** Run agent on input.
+2. **Evaluate Outcome:** Use `test_agent.js` to compare against benchmarks.
+3. **Store and Generate Improvements:** Leverage `memory_agent` to recall past failures and suggest refinements.
+4. **Update and Iterate:** Apply changes and re-test.
+
+**Example Loop in JS (using test_agent.js and memory_agent):**
+```javascript
+// self-improve-loop.js
+const { spawnAgent } = require('../examples/spawn_agent');
+const { testAgent } = require('../examples/test_agent');
+const { memoryAgent } = require('../lib/memory_agent'); // Assuming memory agent for evaluation storage
+
+async function selfImproveLoop(initialConfig, task, maxIterations = 5) {
+  let agent = await spawnAgent(initialConfig);
+  const memory = memoryAgent(); // For storing evaluations
+
+  for (let i = 0; i < maxIterations; i++) {
+    const result = await agent.execute(task);
+    const testResult = await testAgent(agent, { input: task, output: result, expected: /desired pattern/ });
+    
+    // Store in memory
+    await memory.store({ iteration: i, test: testResult });
+    
+    if (testResult.passed) {
+      console.log('Improvement loop converged.');
+      break;
+    }
+    
+    // Retrieve past suggestions from memory
+    const pastFeedback = await memory.retrieve('improvements');
+    const improvements = await agent.suggestImprovements(testResult.feedback, pastFeedback);
+    agent.updateConfig(improvements);
+    
+    console.log(`Iteration ${i + 1}: Updated agent config.`);
+  }
+  
+  return agent;
+}
+
+// Usage
+selfImproveLoop(
+  { name: 'improving-agent', prompt: 'Initial prompt.' },
+  'Complex query here.'
+).catch(console.error);
+```
+
+For scaling to networks of agents, integrate with concepts from [agent-networking.md](./agent-networking.md), such as peer-to-peer spawning.
+
+## Best Practices
+- Always backup agent configs before improvements.
+- Use version control for agent definitions (e.g., JSON specs in `./agents/`).
+- Monitor resource usage in loops to avoid infinite iterations.
+- Test in isolated environments.
+
+## Upcoming Features (v0.0.7)
+For planned enhancements related to agent spawning, testing, and self-improvement, refer to the tasks outlined in [TODO.md](../TODO.md). This includes improvements to loop efficiency, better memory integration, and expanded tool support.
+
+For more on agent workflows, explore related docs like [agent-networking.md](./agent-networking.md).

package/docs/howtos/spawn-agents.md.bak_new

@@ -0,0 +1,200 @@
+# Spawning and Managing Agents
+
+This guide covers how to directly call agents, use the Spawn Dave workflow, and utilize Spawn Agent for creating, testing, and improving agents. It includes practical examples in Bash and JavaScript, as well as concepts for self-improvement loops. For foundational concepts on agent interactions, refer to [agent-networking.md](./agent-networking.md).
+
+## 1. Direct Agent Calls
+
+Direct agent calls allow you to invoke specific agents from the command line or scripts without spawning a full workflow. This is useful for quick queries or testing individual agent behaviors.
+
+### Real Project Example: Calling GPT Agent
+
+In the project, you can directly invoke the GPT agent using the provided script.
+
+**JavaScript Snippet (examples/gpt_agent.js):**
+```javascript
+// examples/gpt_agent.js
+const { createAgent } = require('../lib/agent-factory'); // Assuming agent factory module
+
+async function runAgent(query) {
+  const agent = createAgent('gpt'); // Initialize GPT agent
+  const response = await agent.process(query);
+  console.log(response);
+}
+
+if (require.main === module) {
+  const query = process.argv[2];
+  if (!query) {
+    console.error('Usage: node examples/gpt_agent.js "your query"');
+    process.exit(1);
+  }
+  runAgent(query).catch(console.error);
+}
+```
+
+**Bash Command to Run:**
+```bash
+node examples/gpt_agent.js "What is the capital of France?"
+# Output: Paris (or similar GPT response)
+```
+
+This is a real example from the project, enabling straightforward execution. Extend it by passing additional flags for configuration, e.g., `--model gpt-4`.
+
+## 2. Spawn Dave Workflow
+
+The Spawn Dave workflow (examples/spawn_dave.js) is a predefined sequence for initializing a "Dave" agent instance, which handles complex tasks like multi-step reasoning or integration with external tools.
+
+### Overview
+- **Purpose:** Spawn a Dave agent that can orchestrate sub-agents or workflows.
+- **Key Features:** Tool integration, state management, and logging.
+
+### Example: Running Spawn Dave
+
+**JavaScript Snippet (examples/spawn_dave.js):**
+```javascript
+// examples/spawn_dave.js
+const { spawnDave } = require('../workflows/spawn-dave'); // Import workflow
+
+async function main(task) {
+  const dave = await spawnDave({ 
+    tools: ['web_search', 'code_executor'], 
+    model: 'gpt-4' 
+  });
+  const outcome = await dave.execute(task);
+  console.log('Dave's response:', outcome);
+}
+
+if (require.main === module) {
+  const task = process.argv[2] || 'Default task: Analyze market trends.';
+  main(task).catch(console.error);
+}
+```
+
+**Bash Command:**
+```bash
+node examples/spawn_dave.js "Summarize recent AI advancements."
+```
+
+This workflow automatically handles agent lifecycle: spawn, execute, and cleanup. For networking multiple Daves, see [agent-networking.md](./agent-networking.md).
+
+## 3. Spawn Agent (examples/spawn_agent.js or agentDave)
+
+Spawn Agent is a utility for dynamically creating, testing, and improving agents based on outcomes. It's ideal for iterative development, where agents self-improve through workflows and tests. The entry point is `examples/spawn_agent.js`, which can be aliased as `agentDave` via the `package.json` scripts (e.g., `npm run agentDave -- create ...`).
+
+### Core Functionality
+- **Creating Agents:** Define agent specs (prompts, tools, models) and spawn instances.
+- **Testing:** Run predefined tests to evaluate performance.
+- **Improving:** Use feedback loops to refine prompts or configurations based on outcomes.
+- **Self-Improvement Loops:** Agents can analyze their own outputs and suggest updates.
+
+### Example: Basic Spawn and Test
+
+**Bash Usage (via examples/spawn_agent.js or npm run agentDave):**
+```bash
+# Spawn a new agent for math tasks
+node examples/spawn_agent.js create --name math-solver --tools calculator --prompt "Solve math problems step-by-step."
+
+# Or using alias
+npm run agentDave -- create --name math-solver --tools calculator --prompt "Solve math problems step-by-step."
+
+# Test the agent
+node examples/spawn_agent.js test --name math-solver --input "2+2*3" --expected 8
+
+# Improve based on outcomes
+node examples/spawn_agent.js improve --name math-solver --feedback "Failed on algebra; add quadratic formula."
+```
+
+**JavaScript Integration (Custom Script):**
+```javascript
+// test-spawn.js
+const { spawnAgent, testAgent, improveAgent } = require('../examples/spawn_agent');
+
+async function workflow() {
+  // Create
+  const agent = await spawnAgent({
+    name: 'researcher',
+    tools: ['web_search', 'browse_page'],
+    prompt: 'Conduct thorough research on topics.'
+  });
+
+  // Test
+  const testResult = await testAgent(agent, { query: 'Latest on quantum computing', expected: /qubits/ });
+  console.log('Test passed:', testResult.passed);
+
+  // Self-Improvement Loop
+  if (!testResult.passed) {
+    const improvements = await improveAgent(agent, testResult.feedback);
+    console.log('Suggested improvements:', improvements);
+    // Re-spawn with updates
+    const updatedAgent = await spawnAgent({ ...agent.config, prompt: improvements.newPrompt });
+  }
+}
+
+workflow().catch(console.error);
+```
+
+**Running the Script:**
+```bash
+node test-spawn.js
+```
+
+### Self-Improvement Loops
+Implement loops where agents evaluate their performance using tools like `test_agent.js` for testing and `memory_agent` for storing past evaluations and improvements.
+
+1. **Execute Task:** Run agent on input.
+2. **Evaluate Outcome:** Use `test_agent.js` to compare against benchmarks.
+3. **Store and Generate Improvements:** Leverage `memory_agent` to recall past failures and suggest refinements.
+4. **Update and Iterate:** Apply changes and re-test.
+
+**Example Loop in JS (using test_agent.js and memory_agent):**
+```javascript
+// self-improve-loop.js
+const { spawnAgent } = require('../examples/spawn_agent');
+const { testAgent } = require('../examples/test_agent');
+const { memoryAgent } = require('../lib/memory_agent'); // Assuming memory agent for evaluation storage
+
+async function selfImproveLoop(initialConfig, task, maxIterations = 5) {
+  let agent = await spawnAgent(initialConfig);
+  const memory = memoryAgent(); // For storing evaluations
+
+  for (let i = 0; i < maxIterations; i++) {
+    const result = await agent.execute(task);
+    const testResult = await testAgent(agent, { input: task, output: result, expected: /desired pattern/ });
+    
+    // Store in memory
+    await memory.store({ iteration: i, test: testResult });
+    
+    if (testResult.passed) {
+      console.log('Improvement loop converged.');
+      break;
+    }
+    
+    // Retrieve past suggestions from memory
+    const pastFeedback = await memory.retrieve('improvements');
+    const improvements = await agent.suggestImprovements(testResult.feedback, pastFeedback);
+    agent.updateConfig(improvements);
+    
+    console.log(`Iteration ${i + 1}: Updated agent config.`);
+  }
+  
+  return agent;
+}
+
+// Usage
+selfImproveLoop(
+  { name: 'improving-agent', prompt: 'Initial prompt.' },
+  'Complex query here.'
+).catch(console.error);
+```
+
+For scaling to networks of agents, integrate with concepts from [agent-networking.md](./agent-networking.md), such as peer-to-peer spawning.
+
+## Best Practices
+- Always backup agent configs before improvements.
+- Use version control for agent definitions (e.g., JSON specs in `./agents/`).
+- Monitor resource usage in loops to avoid infinite iterations.
+- Test in isolated environments.
+
+## Upcoming Features (v0.0.7)
+For planned enhancements related to agent spawning, testing, and self-improvement, refer to the tasks outlined in [TODO.md](../TODO.md). This includes improvements to loop efficiency, better memory integration, and expanded tool support.
+
+For more on agent workflows, explore related docs like [agent-networking.md](./agent-networking.md).

package/docs/jsdoc-best-practices.md

@@ -0,0 +1,278 @@
+# JSDoc Best Practices for JavaScript Modules
+
+## Introduction
+
+JSDoc is a markup language used to annotate JavaScript source code files. It allows developers to document their code in a structured way, generating documentation that is readable by humans and machines alike. This is particularly valuable for JavaScript modules, especially toolsets or utility libraries, where clear documentation helps users understand APIs, types, and usage.
+
+Best practices ensure documentation is consistent, comprehensive, and maintainable. Key benefits include:
+- Improved code readability and maintainability.
+- IDE support for autocompletion, type checking, and hover tooltips.
+- Generation of static HTML documentation sites.
+- Reusability across teams and projects.
+
+This guide focuses on documenting functions, classes, parameters, returns, and types, with examples tailored to utility libraries.
+
+## Documenting Modules
+
+Use the `@module` tag to mark a file as a module. All symbols in the file become module members. For utility libraries, document exports explicitly.
+
+### Example: Exporting Functions in a Utility Module
+```javascript
+/**
+ * @module utils/string
+ * String manipulation utilities.
+ */
+
+/**
+ * Formats a string by capitalizing the first letter.
+ * @param {string} str - The input string.
+ * @returns {string} The formatted string.
+ * @example
+ * capitalize("hello world"); // "Hello world"
+ */
+function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+module.exports = { capitalize };
+```
+
+This creates a documented module `module:utils/string` with exported member `module:utils/string.capitalize`.
+
+### Namespaces for Organization
+For larger libraries, use `@namespace` to group related utilities.
+```javascript
+/**
+ * @module math
+ * @namespace math.utils
+ */
+```
+
+## Documenting Functions
+
+Functions are the core of utility libraries. Use `@param` for parameters, `@returns` for return values, and include types and descriptions.
+
+### Basic Function Documentation
+```javascript
+/**
+ * Adds two numbers.
+ * @param {number} a - The first number.
+ * @param {number} b - The second number.
+ * @returns {number} The sum of a and b.
+ * @throws {Error} If inputs are not numbers.
+ * @example
+ * add(2, 3); // 5
+ */
+function add(a, b) {
+    if (typeof a !== "number" || typeof b !== "number") {
+        throw new Error("Inputs must be numbers");
+    }
+    return a + b;
+}
+```
+
+### Optional Parameters and Defaults
+```javascript
+/**
+ * Formats a number with thousand separators.
+ * @param {number} value - The number to format.
+ * @param {string} [separator=","] - The separator (default: comma).
+ * @returns {string} The formatted string.
+ * @example
+ * formatNumber(1000); // "1,000"
+ * formatNumber(1000, "."); // "1.000"
+ */
+function formatNumber(value, separator = ",") {
+    return value.toLocaleString("en-US", { separator });
+}
+```
+
+### Variadic (Rest) Parameters
+```javascript
+/**
+ * Sums multiple numbers.
+ * @param {...number} nums - Numbers to sum.
+ * @returns {number} The total sum.
+ * @example
+ * sum(1, 2, 3); // 6
+ */
+function sum(...nums) {
+    return nums.reduce((acc, n) => acc + n, 0);
+}
+```
+
+### Asynchronous Functions
+```javascript
+/**
+ * Fetches data asynchronously.
+ * @param {string} url - The URL to fetch.
+ * @returns {Promise<Object>} A promise resolving to the data.
+ */
+async function fetchData(url) {
+    const response = await fetch(url);
+    return response.json();
+}
+```
+
+## Documenting Classes
+
+For classes in utility libraries (e.g., a Validator class), document constructors, methods, and properties. JSDoc 3.4+ auto-detects ES6 classes.
+
+### Simple Class Example
+```javascript
+/**
+ * A utility class for validating inputs.
+ */
+class Validator {
+    /**
+     * Creates a new Validator instance.
+     * @param {Object} options - Configuration options.
+     * @param {boolean} [options.strict=false] - Strict mode.
+     */
+    constructor(options = {}) {
+        this.strict = options.strict || false;
+    }
+
+    /**
+     * Validates an email address.
+     * @param {string} email - The email to validate.
+     * @returns {boolean} True if valid.
+     * @memberof Validator
+     */
+    validateEmail(email) {
+        const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return regex.test(email);
+    }
+
+    /**
+     * Static method to validate without instance.
+     * @param {string} email - The email to validate.
+     * @returns {boolean} True if valid.
+     * @static
+     */
+    static isValidEmail(email) {
+        const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return regex.test(email);
+    }
+}
+```
+
+### Extending Classes
+```javascript
+/**
+ * Advanced validator extending basic Validator.
+ * @extends Validator
+ */
+class AdvancedValidator extends Validator {
+    /**
+     * @param {Object} options - Options.
+     * @param {number} options.maxLength - Max length.
+     */
+    constructor(options) {
+        super(options);
+        this.maxLength = options.maxLength || 255;
+    }
+
+    /**
+     * Validates with length check.
+     * @param {string} str - The string.
+     * @returns {boolean} True if valid.
+     * @override
+     */
+    validateEmail(str) {
+        return super.validateEmail(str) && str.length <= this.maxLength;
+    }
+}
+```
+
+## Type Annotations
+
+Use types in curly braces `{}` for precision. Define complex types with `@typedef` for reuse.
+
+### Basic Types
+- Primitives: `{string}`, `{number}`, `{boolean}`
+- Arrays: `{string[]}` or `{Array.<string>}`
+- Objects: `{Object}`
+- Unions: `{string|number}`
+- Nullable: `{string?}`
+- Any: `{*}`
+- Promises: `{Promise<string>}`
+
+### Variables and Properties
+```javascript
+/** @type {string} */
+let message = "Hello";
+
+/**
+ * User object type.
+ * @typedef {Object} User
+ * @property {string} name - User name.
+ * @property {number} age - User age.
+ * @property {string[]} hobbies - User hobbies.
+ */
+
+/** @type {User} */
+const user = { name: "Alice", age: 30, hobbies: ["reading"] };
+```
+
+### In Parameters and Returns
+Types are integrated into `@param` and `@returns`:
+```javascript
+/**
+ * Processes a user.
+ * @param {User} user - The user object.
+ * @returns {User} Processed user.
+ */
+function processUser(user) {
+    return { ...user, processed: true };
+}
+```
+
+## Advanced: Typedefs for Complex Types
+For utility libraries, define reusable types:
+```javascript
+/**
+ * Response from API.
+ * @typedef {Object} ApiResponse
+ * @property {boolean} success - Success flag.
+ * @property {any} data - Response data.
+ * @property {string} [error] - Error message if failed.
+ */
+
+/**
+ * Fetches API data.
+ * @param {string} endpoint - API endpoint.
+ * @returns {Promise<ApiResponse>} The API response.
+ */
+async function apiFetch(endpoint) {
+    // Implementation
+}
+```
+
+## Best Practices
+
+1. **Consistency**: Use the same style for all docs (e.g., always include types, descriptions).
+2. **Readability**: 
+   - Start descriptions with a capital letter and end with a period.
+   - Use hyphens for parameter descriptions: `@param {type} name - Description.`
+   - Keep comments concise but informative.
+3. **Completeness**: Document all public APIs; use `@private` or `@internal` for internals.
+4. **Examples**: Include `@example` blocks for complex usage.
+5. **Namespaces**: Group related items with `@namespace` and `@memberOf` for large libraries.
+   ```javascript
+   /**
+    * @namespace utils.array
+    * Array utility functions.
+    */
+   ```
+6. **Error Handling**: Use `@throws` for possible exceptions.
+7. **Links**: Use `@see` for related items, `@link` for external.
+8. **IDE Integration**: Test in VS Code or WebStorm for type hints.
+9. **Generation**: Use JSDoc CLI (`jsdoc yourfile.js`) to generate HTML docs. Configure with `jsdoc.json` for templates like docdash.
+10. **Maintenance**: Update docs alongside code changes; treat as code.
+
+For toolsets/utility libraries, prioritize documenting exports and focus on user-facing APIs to make integration easy.
+
+## References
+- [Official JSDoc Documentation](https://jsdoc.app/)
+- [JSDoc Tags](https://jsdoc.app/tags-*)