@j-o-r/hello-dave 0.1.0 → 0.1.4

package/docs/toolset.md

@@ -1,164 +0,0 @@
-# ToolSet (\`lib/ToolSet.js\`)
-
-## Overview
-**ToolSet** manages LLM function calls (tools): registration, execution, listing. Integrates with \`Prompt.js\` (via \`execute(prompt)\`) and \`AgentManager.js\` (pre-configured modes, generics). Supports JSON Schema params, async methods. Exports from \`lib/genericToolset.js\`: \`toolsPool\` (11 pre-built tools).
-
-**Uses named exports from \`lib/index.js\` - NO default export.**
-
-Key Features:
-- **Modes**: \`toolChoice: 'auto'|'none'|'required'\` (default \`'auto'\`).
-- **Validation**: Name regex \`/^\[#![a-z_0-9]{2,}$/\`.
-- **Events** (via \`Prompt\`): \`tool_request\`, \`tool_error\`, \`tool_response\`.
-- **Execution**: \`execute(prompt)\` processes \`function_request\`s from last message → calls → adds \`function_response\`s.
-
-## Constructor
-\`\`\`javascript
-import { ToolSet } from '@j-o-r/hello-dave';
-
-new ToolSet(choice = 'auto');  // 'auto'|'none'|'required'
-\`\`\`
-
-## Methods
-| Method | Args | Returns | Description |
-|--------|------|---------|-------------|
-| \`add(name, desc, params, method)\` | \`string\`, \`string\`, \`TSSchema\`, \`async (params) => *\` | \`void\` | Register tool. Overwrites if exists. |
-| \`get(name)\` | \`string\` | \`TSTool\` | Get tool details. |
-| \`delete(name)\` | \`string\` | \`void\` | Remove tool. |
-| \`has(name)\` | \`string\` | \`boolean\` | Exists? |
-| \`list()\` | - | \`TSToolListItem[]\` (sorted) | All tools (name/desc/params). |
-| \`call(name, params)\` | \`string\`, \`object\` | \`Promise<*\>\` | Execute tool. |
-| \`execute(prompt)\` | \`Prompt\` | \`Promise<void>\` | Process last message \`function_request\`s → execute → add \`function_response\`s to \`tool\` role. |
-| \`length\` | - | \`number\` | Tool count. |
-| \`toolChoice\` | - | \`string\` | Getter for mode. |
-
-**TSTool**: \`{description: string, parameters: TSSchema, method: async (params) => *}\`  
-**TSSchema**: OpenAI-style JSON Schema (\`{type: 'object', properties: {...}, required: [...]}\`).
-
-## Generic Tools (\`lib/genericToolset.js\` → \`toolsPool\`)
-| `syntax_check` | Validate syntax (JS/Py/Bash/JSON) via utils/syntax_check.sh. |\n|-----|-----|
-Pre-built \`ToolSet('auto')\` with **11 tools**. Copied via \`AgentManager.addGenericToolcall(name)\` or \`toolsetMode: 'auto'\`.
-
-| Tool Name                  | Description |
-|----------------------------|-------------|
-| \`javascript_interpreter\` | Execute ESM ES6 JavaScript on \`node\`. \`console.log\` captures output. cwd: \`~/devpri/js/hello-dave\`. |
-| \`get_user_env\`           | Get user environment (name, system, city/region/country/timezone, external IP). |
-| \`execute_bash_script\`    | Execute raw Bash script/command (no escaping; verbatim \`$\| < > & " ' \\\\` newlines \`$(())\` \`[[ ]]\`. Heredoc-safe). Ubuntu 25.10. |
-| \`send_email\`             | Send email via \`msmtp\` (to, subject, body). |
-| \`open_link\`              | Open URL/file with \`xdg-open\`. |
-| \`execute_remote_script\`  | Execute raw Bash on remote via SSH (\`ssh://user@host[:port]\`). |
-| \`history_search\`         | Search chat sessions: \`"(todo\\|task)"\` or \`"package.json"\`. Regex in \`.cache/[app]/[prompt]/sessions/*.ndjson\`. |
-| \`read_file\`              | Read raw file in CWD (relative path, no \`/\` \`..\` \`\\\\\`). |
-| \`write_file\`             | Write raw content to file in CWD (relative, as-is; no escaping). Returns bytes written. |
-| \`memory_recall\`          | Recall persistent memory entries from agent-specific storage (\`.cache/[agent]/memory.ndjson\`). |
-| \`memory_write\`           | Write/update persistent memory entries for long-term state (\`.cache/[agent]/memory.ndjson\`). |
-
-## Memory Tools (New)
-These tools provide persistent, agent-specific memory storage in NDJSON format (\`.cache/[agent-name]/memory.ndjson\`). Append-only; latest value per key. Ideal for token efficiency by offloading state/decisions from context.
-
-### \`memory_recall\`
-**Description**: Retrieve the latest values for specified keys from memory file. Returns JSON: \`{key: value, ...}\` or \`{}\` if missing.
-
-**Parameters**:
-\`\`\`json
-{
-  "type": "object",
-  "properties": {
-    "keys": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "List of memory keys to recall, e.g., ['current_task', 'last_decision']"
-    }
-  },
-  "required": ["keys"]
-}
-\`\`\`
-
-**Example Usage in Agent Prompt**:
-\`\`\`
-Before proceeding, recall your current task and previous decision:
-- Call memory_recall with keys: ["current_task", "last_decision"]
-Then, use the recalled info to avoid repetition.
-\`\`\`
-
-**Token Efficiency**: Stores tasks/decisions externally. Recall only needed state (e.g., 100 tokens) vs. full history (10k+ tokens), preventing loops/re-reasoning.
-
-### \`memory_write\`
-**Description**: Append/update key-value pairs to memory (overwrites prior same-key entries). Returns confirmation with stored entries.
-
-**Parameters**:
-\`\`\`json
-{
-  "type": "object",
-  "properties": {
-    "entries": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "properties": {
-          "key": { "type": "string", "description": "Unique key (e.g., 'current_task')" },
-          "value": { "type": "string", "description": "JSON-stringifiable value" }
-        },
-        "required": ["key", "value"]
-      },
-      "description": "List of {key, value} pairs to store"
-    }
-  },
-  "required": ["entries"]
-}
-\`\`\`
-
-**Example Usage in Agent Prompt**:
-\`\`\`
-After analyzing, store the plan:
-- Call memory_write with entries: [{"key": "current_task", "value": "Implement login feature"}, {"key": "step", "value": "1/5"}]
-\`\`\`
-
-**Token Efficiency**: Persist intermediate results across calls/sessions. Avoids context explosion/loops by recalling compact state instead of regenerating.
-
-## Integration with AgentManager
-In \`setup()\`:
-\`\`\`javascript
-agent.setup({
-  toolsetMode: 'auto',  // Loads all 11 generic tools
-  // or 'required': Empty ToolSet (add manually)
-});
-agent.addGenericToolcall('memory_recall');  // Selective copy post-setup
-\`\`\`
-
-**Custom Tools**:
-\`\`\`javascript
-import { AgentManager } from '@j-o-r/hello-dave';
-
-agent.setup({ toolsetMode: 'required' });
-const ts = agent.getToolset();
-ts.add('math', 'Add numbers', {
-  type: 'object',
-  properties: {a: {type: 'number'}, b: {type: 'number'}},
-  required: ['a', 'b']
-}, async ({a, b}) => a + b);
-\`\`\`
-
-**Workflow** (in \`Prompt.call()\` / API adapters):
-1. LLM → \`function_request\`s (assistant message).
-2. \`ToolSet.execute(prompt)\` → parallel \`call()\` → \`function_response\`s (tool message).
-3. Recurse until text response.
-
-## Examples
-### Standalone ToolSet
-\`\`\`javascript
-import { ToolSet } from '@j-o-r/hello-dave';
-
-const ts = new ToolSet('required');
-ts.add('hello', 'Say hello', {type: 'object', properties: {name: {type: 'string'}}, required: ['name']},
-  async ({name}) => \`Hello, \${name}!\`);
-console.log(await ts.call('hello', {name: 'World'}));  // "Hello, World!"
-\`\`\`
-
-### With Prompt/AgentManager
-See [AgentManager](./agent-manager.md#custom-tools--generics), [Prompt](./prompt-class.md).
-
-**Updated:** March 26, 2026 (11 generics from \`lib/genericToolset.js\`).
-
-See also: [GenericToolset Source](./generic-toolset.md).
-\n## Syntax Validation\nSee [tools-syntax-validation.md](tools-syntax-validation.md) for `write_file` JS checks + `syntax_check` tool.
-\n## Path Resolution\nSee [path-resolution-best-practices.md](path-resolution-best-practices.md) for __dirname vs cwd() in tools (e.g., syntax_check.sh).\\n

package/docs/xai-responses.md

@@ -1,111 +0,0 @@
-# xAI Responses API Integration (`lib/API/x.ai/responses.js`)
-
-## Overview
-This module provides a seamless wrapper for the [xAI Responses API](https://docs.x.ai/docs/api-reference#create-new-response) (formerly Grok API), adapted for the hello-dave framework. It integrates directly with `Prompt.js` and `ToolSet.js`, enabling tool-using agents via `AgentManager`.
-
-**Uses named exports from `lib/index.js` - NO default export.**
-
-Key adaptations:
-- **Unified Interface**: Uses `Prompt` messages/history for input; parses `output` into assistant/tool responses.
-- **Recursive Tool Calls**: Automatically handles `function_call` → execute tools → `function_call_output` loops (up to `GLOBAL.max_recursive_requests`).
-- **Tool Support**: Converts `ToolSet` to xAI `function` tools; supports native xAI tools like `web_search`, `x_search`.
-- **Reasoning & Search**: Configurable `reasoning.effort` (`low`/`medium`/`high`), `search_parameters`.
-- **Streaming**: Not yet implemented (future).
-- **Auth**: Requires `XAIKEY` env var.
-
-Default model: `grok-4-fast-reasoning`. Supports: `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning`, etc.
-
-## Usage in AgentManager
-```javascript
-import { AgentManager } from '@j-o-r/hello-dave';
-
-const agent = new AgentManager({ name: 'weatheragent', secret: 'optional-ws-secret' });
-agent.setup({
-  prompt: 'You are a precise weather expert. Use tools for real-time data.',
-  api: 'xai',
-  options: { model: 'grok-4-fast-reasoning', reasoning: { effort: 'high' } },
-  toolsetMode: 'auto',  // Adds generic tools like web_search
-  contextWindow: 128000
-});
-agent.addGenericToolcall('web_search');  // Optional: Add extras
-
-// CLI mode
-agent.start();  // Interactive chat
-
-// Or direct call
-const response = await agent.directCall('Weather in Amsterdam today?');
-console.log(response);  // Handles search/tools automatically
-```
-
-Under the hood:
-1. `Prompt.setAdaptor(API.text['xai'], toolset, options)` → uses `responses.request()`.
-2. Converts history to xAI `input[]` (system/user/assistant/tool).
-3. POST to `https://api.x.ai/v1/responses`.
-4. Parses `output` → adds text/reasoning/tools to `Prompt`.
-5. If tools needed, `ToolSet.execute()` → recurse until complete.
-
-## Options (XAIOptions)
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `model` | string | `'grok-4-fast-non-reasoning'` | e.g., `'grok-4-fast-reasoning'` |
-| `input` | `XAIInput[]` | `[{role: 'system', content: 'Be precise'}]` | Messages/history |
-| `reasoning.effort` | `'low'\|'medium'\|'high'` | `'medium'` | Reasoning depth |
-| `reasoning.summary` | `'auto'\|'concise'\|'detailed'` | `'auto'` | Reasoning output style |
-| `temperature` | number | `1` (0-2) | Sampling |
-| `parallel_tool_calls` | boolean | `true` | Parallel functions |
-| `tool_choice` | `'auto'` | `'auto'` | Tool selection |
-| `tools` | `XAIFunctionTool[]` | `[]` | From `ToolSet` |
-| `store` | boolean | `false` | Persist response (still bills tokens) |
-| `max_output_tokens` | number | `4000` | Limit |
-| `search_parameters` | object | - | `{max_search_results: 4, mode: 'auto', return_citations: true}` |
-
-**Tool Types**:
-- `function`: From `ToolSet` (name, description, parameters JSONSchema).
-- Native: `web_search`, `x_search` (filters: dates, domains, etc.).
-
-## Example Request (Generated Internally)
-```json
-{
-  "model": "grok-4-fast-reasoning",
-  "input": [
-    {"role": "system", "content": "You are a precise weather expert."},
-    {"role": "user", "content": "Weather in Amsterdam today?"}
-  ],
-  "parallel_tool_calls": true,
-  "reasoning": {"effort": "high"},
-  "search_parameters": {"mode": "auto", "return_citations": true},
-  "tools": [{"type": "function", "name": "web_search", ...}]
-}
-```
-
-## Example Response (Parsed to Prompt)
-- **Text + Citations**: Added as `assistant` text + `log` annotations (URLs).
-- **Function Calls**: `assistant` with `function_request` → `ToolSet.execute()`.
-- **Reasoning**: Prepended as `reasoning` multimodal text.
-
-Sample parsed:
-```
-Today is [date]. Weather: Cloudy, 5°C... [citations]
-```
-Tokens: `input_tokens`, `output_tokens` (incl. `reasoning_tokens`) logged in `Prompt.records`.
-
-## Advanced: Custom Tools
-Extend `ToolSet` before `setup()`:
-```javascript
-import { ToolSet } from '@j-o-r/hello-dave';
-
-const ts = new ToolSet('required');
-ts.add('get_weather', 'Get weather for a location', {
-  type: 'object',
-  properties: { location: {type: 'string'} },
-  required: ['location']
-}, async (params) => `Weather: ${params.location} - 20°C`);  // Handler
-agent.setup({ ..., toolsetMode: ts });
-```
-
-## Errors & Limits
-- `Max recursive calls`: `GLOBAL.max_recursive_requests`.
-- Missing `XAIKEY`: Throws.
-- Invalid last message: Must end in `user`/`tool`.
-
-See `lib/API/x.ai/responses.js` source for full JSDoc/types. Cross-links: [Prompt](../prompt-class.md), [ToolSet](../toolset.md), [AgentManager](agent-manager.md).

package/docs/xai_collections.md

@@ -1,106 +0,0 @@
-[x.ai collections](https://docs.x.ai/docs/guides/using-collections/api)
-
-
-Creating a collection:
-
-```bash
-curl https://management-api.x.ai/v1/collections \
-  -X POST \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
-  -d '{"collection_name": "SEC Filings"}'
-```
-
-Listing collections:
-```bash
-curl https://management-api.x.ai/v1/collections \
-  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
-```
-
-Viewing collection configuration:
-```bash
-'curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d \
-  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
-```
-
-Updating collection configuration
-```bash
-curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d \
-  -X PUT \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
-  -d '{"collection_name": "SEC Filings (New)"}'
-```
-
-Uploading documents:
-
-```bash
-# Step 1: Upload file
-curl https://api.x.ai/v1/files \
-  -H "Authorization: Bearer $XAI_API_KEY" \
-  -F file=@tesla-20241231.html
-
-# Step 2: Add file to collection (use file_id from step 1)
-curl -X POST https://management-api.x.ai/v1/collections/$COLLECTION_ID/documents/$FILE_ID \
-  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
-
-```
-
-Uploading with metadata fields
-
-```bash
-curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d/documents \
-  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
-  -F "name=paper.pdf" \
-  -F "data=@paper.pdf" \
-  -F "content_type=application/pdf" \
-  -F 'fields={"author": "Sandra Kim", "year": "2024", "title": "Q3 Revenue Analysis"}'
-
-```
-
-Searching documents
-
-```bash
-curl https://api.x.ai/v1/documents/search \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $XAI_API_KEY" \
-  -d '{
-    "query": "What were the key revenue drivers based on the SEC filings?",
-    "source": {
-      "collection_ids": ["collection_dbc087b1-6c99-493d-86c6-b401fee34a9d"]
-    }
-  }'
-```
-
-```bash
-curl https://api.x.ai/v1/documents/search \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $XAI_API_KEY" \
-  -d '{
-      "query": "What were the key revenue drivers based on the SEC filings?",
-      "source": {
-          "collection_ids": [
-              "collection_dbc087b1-6c99-493d-86c6-b401fee34a9d"
-          ]
-      },
-      "retrieval_mode": {"type": "hybrid"}
-}'
-```
-
-
-Deleting a document:
-
-```bash
-curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d/documents/file_55a709d4-8edc-4f83-84d9-9f04fe49f832 \
-  -X DELETE \
-  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
-
-```
-
-Deleting a collection
-
-```bash
-curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d \
-  -X DELETE \
-  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
-```

package/lib/API/x.ai/ImageToolset.js

@@ -1,165 +0,0 @@
-/**
- * @file lib/API/x.ai/ImageToolset.js
- * @module x.ai/ImageToolset
- * @description Comprehensive ToolSet for the xAI Grok Imagine API.
- *
- * Exposes high-level tools for:
- *   - generate_image     → Text-to-image generation
- *   - edit_image         → Natural language image editing (supports up to 3 reference images)
- *   - generate_video     → Image-to-video generation (fully automatic)
- *
- * Designed for AI agents and LLMs. Each tool includes rich descriptions and JSON schemas.
- *
- * @see ./image.js for the underlying implementation
- * @see ./image.md for the full API specification
- */
-
-import ToolSet from '../../ToolSet.js';
-import * as xai from './image.js';
-
-const tools = new ToolSet('auto');
-
-/* ============================================================
-   GENERATE IMAGE
-   ============================================================ */
-
-tools.add(
-  'generate_image',
-  'Generate high-quality images from a text prompt using Grok Imagine. ' +
-  'Supports configurable number of images and output format. ' +
-  'Returns the local file path of the generated image(s).',
-  {
-    type: 'object',
-    properties: {
-      prompt: {
-        type: 'string',
-        description: 'Detailed English prompt describing the desired image. ' +
-                     'Be specific about style, lighting, composition, and subject.'
-      },
-      n: {
-        type: 'integer',
-        minimum: 1,
-        maximum: 10,
-        default: 1,
-        description: 'Number of images to generate in one request.'
-      },
-      output_format: {
-        type: 'string',
-        enum: ['png', 'jpeg', 'webp'],
-        default: 'png',
-        description: 'Preferred output format.'
-      }
-    },
-    required: ['prompt']
-  },
-  async (params) => {
-    const result = await xai.generateImage(params.prompt, params);
-
-    return JSON.stringify({
-      local_path: result.local_path,
-      url: result.url,
-      revised_prompt: result.revised_prompt,
-      note: 'Image generated successfully with generate_image.'
-    }, null, 2);
-  }
-);
-
-/* ============================================================
-   EDIT IMAGE
-   ============================================================ */
-
-tools.add(
-  'edit_image',
-  'Edit one or more images using natural language instructions. ' +
-  'Supports up to 3 reference images for compositing, style transfer, or multi-subject editing. ' +
-  'Provide image URLs, local paths, or base64 data.',
-  {
-    type: 'object',
-    properties: {
-      prompt: {
-        type: 'string',
-        description: 'Natural language description of the edit you want to apply.'
-      },
-      image_url: {
-        type: 'string',
-        description: 'Single image URL or path to edit.'
-      },
-      image_urls: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'Array of up to 3 image URLs or paths for multi-image editing.'
-      },
-      output_format: {
-        type: 'string',
-        enum: ['png', 'jpeg', 'webp'],
-        default: 'png'
-      }
-    },
-    required: ['prompt']
-  },
-  async (params) => {
-    const images = params.image_urls || (params.image_url ? [params.image_url] : []);
-
-    const result = await xai.editImage(params.prompt, images, params);
-
-    return JSON.stringify({
-      local_path: result.local_path,
-      url: result.url,
-      revised_prompt: result.revised_prompt,
-      note: 'Image edited successfully with edit_image.'
-    }, null, 2);
-  }
-);
-
-/* ============================================================
-   GENERATE VIDEO
-   ============================================================ */
-
-tools.add(
-  'generate_video',
-  'Generate a video from a still image and text prompt using Grok Imagine Video. ' +
-  'This tool is fully automatic — it submits the request and waits internally until the video is ready. ' +
-  'Returns the local file path of the generated video.',
-  {
-    type: 'object',
-    properties: {
-      prompt: {
-        type: 'string',
-        description: 'Description of the desired motion, camera movement, or animation.'
-      },
-      image_url: {
-        type: 'string',
-        description: 'Source image URL or local path.'
-      },
-      duration: {
-        type: 'number',
-        minimum: 1,
-        maximum: 15,
-        default: 8,
-        description: 'Video duration in seconds.'
-      },
-      aspect_ratio: {
-        type: 'string',
-        default: '16:9',
-        description: 'Aspect ratio of the output video.'
-      },
-      resolution: {
-        type: 'string',
-        default: '720p',
-        description: 'Output resolution.'
-      }
-    },
-    required: ['prompt', 'image_url']
-  },
-  async (params) => {
-    const result = await xai.generateVideo(params.prompt, params.image_url, params);
-
-    return JSON.stringify({
-      local_path: result.local_path,
-      url: result.url,
-      note: 'Video generated successfully with generate_video.'
-    }, null, 2);
-  }
-);
-
-export default tools;