{"_id":"@agentmech/agentmech","_rev":"2-540ce497fd87e705c5da2cbd2fae0f38","name":"@agentmech/agentmech","dist-tags":{"latest":"1.1.5"},"versions":{"1.0.2":{"name":"@agentmech/agentmech","version":"1.0.2","keywords":["ai","workflow","ollama","cli","automation","llm","rag","mcp"],"author":"","license":"ISC","_id":"@agentmech/agentmech@1.0.2","maintainers":[{"name":"mtfuller","email":"MTFULLER1995@GMAIL.COM"}],"homepage":"https://github.com/mtfuller/agentmech#readme","bugs":{"url":"https://github.com/mtfuller/agentmech/issues"},"bin":{"agentmech":"dist/cli.js"},"dist":{"shasum":"eb5f3b6f89c264b412de88cafe39c735fb7cbf8c","tarball":"https://registry.npmjs.org/@agentmech/agentmech/-/agentmech-1.0.2.tgz","fileCount":139,"integrity":"sha512-ZAh+cVDz0HjyBoxgvuol5dEXKial27a6fq1zWIPN1KteDNpSHt/BYr+nAeZxvrhIPW2mnjlije+wstPtqWF70A==","signatures":[{"sig":"MEYCIQDVmnFiGjURu4+S/lj4pFq1I7l1puzixDyHcbLrbK0p7AIhAOPfGYXQ/0DYp2jaZiWSVdBD17Zen/wAjmXmfYI+2XyO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentmech%2fagentmech@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":574720},"main":"dist/cli.js","types":"./dist/cli.d.ts","engines":{"node":">=14.0.0"},"gitHead":"b47b179da8603b1a4abb65d908d84f5dc3357e3e","scripts":{"test":"npm run build && jest","build":"tsc && npm run copy-views","clean":"rm -rf dist","start":"node dist/cli.js","copy-views":"node scripts/copy-views.js","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"mtfuller","email":"MTFULLER1995@GMAIL.COM"},"repository":{"url":"git+https://github.com/mtfuller/agentmech.git","type":"git"},"_npmVersion":"10.8.2","description":"A Node.js CLI tool for running AI workflows locally with Ollama integration","directories":{},"_nodeVersion":"20.19.5","dependencies":{"cors":"^2.8.5","axios":"^1.13.2","chalk":"^4.1.2","express":"^5.1.0","js-yaml":"^4.1.0","mammoth":"^1.11.0","commander":"^14.0.2","pdf-parse":"^1.1.1","@msgpack/msgpack":"^3.1.2","@types/pdf-parse":"^1.1.5"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","jszip":"^3.10.1","pdfkit":"^0.17.2","ts-jest":"^29.1.2","typescript":"^5.9.3","@types/cors":"^2.8.19","@types/jest":"^29.5.12","@types/node":"^24.10.0","@types/chalk":"^0.4.31","@types/express":"^5.0.5","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/agentmech_1.0.2_1762877782412_0.8768721830793587","host":"s3://npm-registry-packages-npm-production"}},"1.1.5":{"name":"@agentmech/agentmech","version":"1.1.5","description":"A Node.js CLI tool for running AI workflows locally with Ollama integration","main":"dist/cli.js","bin":{"agentmech":"dist/cli.js"},"scripts":{"clean":"rm -rf dist","build":"tsc && npm run copy-views","copy-views":"node scripts/copy-views.js","start":"node dist/cli.js","test":"npm run build && jest","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"keywords":["ai","workflow","ollama","cli","automation","llm","rag","mcp"],"author":"","license":"ISC","repository":{"type":"git","url":"git+https://github.com/mtfuller/agentmech.git"},"homepage":"https://github.com/mtfuller/agentmech#readme","bugs":{"url":"https://github.com/mtfuller/agentmech/issues"},"engines":{"node":">=14.0.0"},"dependencies":{"@msgpack/msgpack":"^3.1.2","@types/pdf-parse":"^1.1.5","axios":"^1.13.2","chalk":"^4.1.2","commander":"^14.0.2","cors":"^2.8.5","express":"^5.1.0","js-yaml":"^4.1.0","mammoth":"^1.11.0","pdf-parse":"^1.1.1"},"devDependencies":{"@types/chalk":"^0.4.31","@types/cors":"^2.8.19","@types/express":"^5.0.5","@types/jest":"^29.5.12","@types/js-yaml":"^4.0.9","@types/node":"^24.10.1","jest":"^29.7.0","jszip":"^3.10.1","pdfkit":"^0.17.2","ts-jest":"^29.1.2","typescript":"^5.9.3"},"_id":"@agentmech/agentmech@1.1.5","gitHead":"edeca5c07f4090bd1c0caaaa593f05b62eed48fc","types":"./dist/cli.d.ts","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-iBC41Y9cXgqWYBo3CmDkRTzJRA4c92p42sNvPYurKOyqIiEUiSFDPoQOMUCDaw2X3dVSUrbqqkd3x9K4xMzEUw==","shasum":"82e2199dbfcbd4271708f18538e1aa129abd2e8c","tarball":"https://registry.npmjs.org/@agentmech/agentmech/-/agentmech-1.1.5.tgz","fileCount":143,"unpackedSize":630030,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentmech%2fagentmech@1.1.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDbVwnldwC0VVHE9UM/3IBdkOfxHswK9LTeSkYoVnPwHQIhANP+O5lKZFawjJeYaxPjJiat+50Gh4b2mzvjBeRh669g"}]},"_npmUser":{"name":"mtfuller","email":"MTFULLER1995@GMAIL.COM"},"directories":{},"maintainers":[{"name":"mtfuller","email":"MTFULLER1995@GMAIL.COM"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentmech_1.1.5_1763070143796_0.7741550367420773"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-11T16:16:22.311Z","modified":"2025-11-13T21:42:24.478Z","1.0.2":"2025-11-11T16:16:22.625Z","1.1.5":"2025-11-13T21:42:24.015Z"},"bugs":{"url":"https://github.com/mtfuller/agentmech/issues"},"license":"ISC","homepage":"https://github.com/mtfuller/agentmech#readme","keywords":["ai","workflow","ollama","cli","automation","llm","rag","mcp"],"repository":{"type":"git","url":"git+https://github.com/mtfuller/agentmech.git"},"description":"A Node.js CLI tool for running AI workflows locally with Ollama integration","maintainers":[{"name":"mtfuller","email":"MTFULLER1995@GMAIL.COM"}],"readme":"# AgentMech\n\nA Node.js CLI tool for running AI workflows locally with Ollama. Define complex AI-powered workflows using simple YAML files and execute them with state machine logic.\n\n## Features\n\n- ✨ **Guided Workflow Generation**: Create workflows with AI-powered template selection and customization\n- 🌐 **Web UI**: Browse and manage workflows through a web interface\n- 🤖 **Ollama Integration**: Run AI workflows using local Ollama models with streaming support\n- ⚡ **Real-time Streaming**: See LLM responses token-by-token as they're generated\n- 🖼️ **Multimodal Support**: Process images and text files in your workflows\n- 🔌 **MCP Integration**: Connect to Model Context Protocol servers for extended capabilities\n- 🧠 **RAG Support**: Retrieval-Augmented Generation for context-aware responses\n- 🔍 **Observability**: Trace and log workflow interactions\n- 🧪 **Testing**: Automated test scenarios to validate workflow behavior\n\n## Prerequisites\n\n- Node.js (v14 or higher)\n- [Ollama](https://ollama.ai/) installed and running\n\n## Installation\n\n### From NPM (Recommended)\n\n```bash\nnpm install -g @agentmech/agentmech\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/mtfuller/agentmech.git\ncd agentmech\nnpm install && npm run build\n```\n\n## Quick Start\n\n```bash\n# Start Ollama (separate terminal)\nollama serve\nollama pull gemma3:4b\n\n# Generate a custom workflow\nagentmech generate\n\n# Run a workflow\nagentmech run examples/simple-qa.yaml\n```\n\n## Commands\n\n```bash\n# Generate workflow with guided template selection\nagentmech generate [-o output.yaml] [-m model]\n\n# Run workflow\nagentmech run <workflow.yaml> [--trace] [--log-file path]\n\n# Test workflow\nagentmech test <test.yaml> [--format json|markdown] [--output path]\n\n# Validate workflow\nagentmech validate <workflow.yaml>\n\n# Start web UI\nagentmech serve [workflow-dir] [-p port]\n\n# List Ollama models\nagentmech list-models\n```\n\nEach execution creates a unique run directory at `~/.agentmech/runs/<workflow>-<timestamp>/` containing logs and generated files. Use `--trace` for detailed execution logging.\n\n## Workflow Generation\n\nThe `generate` command provides an interactive, guided workflow creation experience:\n\n```bash\nagentmech generate [-o output.yaml] [-m model]\n```\n\n### How It Works\n\n1. **Describe Your Goal**: Tell AgentMech what you're trying to accomplish\n2. **AI Recommendations**: The LLM analyzes your goal and recommends suitable workflow templates\n3. **Choose a Template**: Select from 2-3 recommended workflow patterns:\n   - **Simple Q&A** - For straightforward questions and information lookup\n   - **User Input Conversation** - For interactive workflows that collect user input\n   - **Sequential Analysis** - For complex tasks requiring multiple processing steps\n   - **Content Generator** - For creative content generation with iterative refinement\n   - **Research Assistant** - For research tasks with intelligent decision-making\n4. **Customize**: Answer template-specific questions to personalize your workflow\n5. **Validate**: The generated workflow is automatically validated before saving\n\n### Example Session\n\n```\n$ agentmech generate\n\nAI Workflow Generator\n\nLet's create a workflow tailored to your needs!\n\nWhat are you trying to accomplish with this workflow? I want to analyze customer feedback\n\nAnalyzing your goal and finding the best workflow patterns...\n\nFound matching workflow patterns!\n\nSelect a workflow template:\n\n1. Sequential Analysis\n   Multi-step workflow with progressive analysis\n   Use case: Best for complex tasks that require multiple AI processing steps\n\n2. User Input Conversation\n   Collect user input and generate personalized responses\n   Use case: Best for interactive workflows that need to gather information\n\nSelect a template (1-2): 1\n\nWhat would you like to name this workflow? (default: Sequential Analysis Workflow):\nCustomer Feedback Analyzer\n...\n```\n\n## Workflow YAML Format\n\n### Basic Structure\n\n```yaml\nname: \"Workflow Name\"\ndescription: \"Optional description\"\ndefault_model: \"gemma3:4b\"\nstart_state: \"first_state\"\n\n# Optional: Define variables for use in prompts\nvariables:\n  my_var: \"value\"\n\nstates:\n  first_state:\n    type: \"prompt\"\n    prompt: \"Your question here\"\n    save_as: \"result\"\n    next: \"end\"\n```\n\n### State Types\n\n**Prompt State** - Send prompts to AI models\n```yaml\nanalyze:\n  type: \"prompt\"\n  prompt: \"Analyze this data\"\n  model: \"gemma3:4b\"              # Optional: Override default\n  files: [\"image.png\", \"data.txt\"] # Optional: Multimodal inputs\n  save_as: \"result\"\n  next: \"next_state\"\n```\n\n**Input State** - Collect user input\n```yaml\nget_name:\n  type: \"input\"\n  prompt: \"What's your name?\"\n  save_as: \"name\"\n  default_value: \"Guest\"\n  next: \"greet\"\n```\n\n**Workflow Reference** - Include another workflow\n```yaml\nsub_task:\n  type: \"workflow_ref\"\n  workflow_ref: \"path/to/other.yaml\"\n  next: \"continue\"\n```\n\n**Sequential Steps** - Execute multiple prompts in sequence within one state\n```yaml\nstory_creation:\n  type: \"prompt\"\n  steps:\n    - prompt: \"Generate a character name\"\n      save_as: \"name\"\n    - prompt: \"Describe {{name}}'s personality\"\n      save_as: \"description\"\n    - prompt: \"Write a story about {{name}}: {{description}}\"\n      save_as: \"story\"\n  next: \"next_state\"\n```\n\nSteps can also be used with `input` states to collect multiple user inputs sequentially. Each step can have its own `prompt`, `save_as`, `model`, and other properties that override state-level settings.\n\n### Advanced Features\n\n**MCP Servers** - Extend with Model Context Protocol\n```yaml\nmcp_servers:\n  filesystem:\n    type: npx\n    package: \"@modelcontextprotocol/server-filesystem\"\n    args: [\"/tmp\"]\n  custom_tools:\n    type: custom-tools\n    toolsDirectory: \"examples/custom-tools\"\n```\n\n**RAG (Retrieval-Augmented Generation)** - Add knowledge base context\n```yaml\nrag:\n  testing:\n    directory: \"./knowledge-base\"\n    chunk_size: 500\n    top_k: 3\n    # NEW: Customize how chunks are injected\n    chunk_template: \"{{number}}. {{chunk.text}}\"\n    context_template: \"Context:\\n{{chunks}}\\n\\nQuery: {{prompt}}\"\n\nstates:\n  answer:\n    type: \"prompt\"\n    prompt: \"{{question}}\"\n    use_rag: \"testing\"  # Uses RAG context\n    next: \"end\"\n```\n\n**Error Handling** - Graceful fallbacks\n```yaml\non_error: \"error_handler\"  # Workflow-level\n\nstates:\n  risky:\n    type: \"prompt\"\n    prompt: \"...\"\n    on_error: \"specific_handler\"  # State-level\n    next: \"success\"\n```\n\n**Dynamic Routing** - LLM chooses next state\n```yaml\nanalyze:\n  type: \"prompt\"\n  prompt: \"Analyze: {{input}}\"\n  next_options:\n    - state: \"deep_dive\"\n      description: \"Needs detailed analysis\"\n    - state: \"quick_summary\"\n      description: \"Simple summary sufficient\"\n```\n\n### Variable Interpolation\n\nUse `{{variable_name}}` to reference variables in prompts and file paths.\n\n**Define workflow-level variables:**\n```yaml\nvariables:\n  # Inline value (shorthand)\n  user_name: \"Alice\"\n  \n  # Inline value (object syntax)\n  topic:\n    value: \"artificial intelligence\"\n  \n  # Load from file\n  system_prompt:\n    file: \"prompts/template.txt\"\n\nstates:\n  greet:\n    type: \"prompt\"\n    prompt: \"{{system_prompt}}\\n\\nHello {{user_name}}! Let's discuss {{topic}}.\"\n    save_as: \"response\"\n    next: \"end\"\n```\n\n**Built-in variables:**\n- `{{run_directory}}` - Current execution directory\n\n**Runtime variables:**\nVariables saved with `save_as` can be used in subsequent states and will override workflow-level variables with the same name.\n\n### Multimodal Support\n\nAttach files to prompts for image and document analysis:\n```yaml\nanalyze:\n  type: \"prompt\"\n  prompt: \"What's in these files?\"\n  model: \"llava\"  # Use vision models for images\n  files: [\"image.png\", \"data.txt\", \"{{run_directory}}/output.json\"]\n  next: \"end\"\n```\n\nSupported: Images (`.jpg`, `.png`, etc.), text files (`.txt`, `.md`, `.json`, `.yaml`, `.csv`)\n\n## Testing\n\nCreate test files to validate workflow behavior with mocked inputs and assertions:\n\n```yaml\nworkflow: user-input-demo.yaml\ntest_scenarios:\n  - name: \"User Flow Test\"\n    inputs:\n      - state: \"get_name\"\n        value: \"Alice\"\n    assertions:\n      - type: \"equals\"\n        target: \"name\"\n        value: \"Alice\"\n      - type: \"contains\"\n        target: \"response\"\n        value: \"Alice\"\n      - type: \"state_reached\"\n        value: \"end\"\n```\n\n**Assertion types:** `equals`, `contains`, `not_contains`, `regex`, `state_reached`\n\nRun tests: `agentmech test workflow.test.yaml [--format json|markdown] [--output report.json]`\n\n## Examples\n\nBrowse the `examples/` directory for sample workflows:\n- **simple-qa.yaml** - Basic Q&A workflow\n- **sequential-steps-demo.yaml** - Sequential prompts with steps feature\n- **user-survey-steps.yaml** - Multiple user inputs with steps\n- **image-analysis.yaml** - Analyze images with vision models\n- **multi-rag-qa.yaml** - RAG with multiple knowledge bases\n- **research-assistant.yaml** - LLM-driven state routing\n- **comprehensive-mcp-integration.yaml** - MCP server integration\n- **simple-web-browse.yaml** - Web browsing with Playwright MCP server\n- **web-browsing-demo.yaml** - Interactive web browsing workflow\n- **complete-story-builder.yaml** - Workflow composition\n- **user-input-demo.test.yaml** - Test scenarios\n\nSee [examples/](examples/), [examples/WEB_BROWSING_GUIDE.md](examples/WEB_BROWSING_GUIDE.md), and [docs/USAGE.md](docs/USAGE.md) for more.\n\n## Documentation\n\n- [ARCHITECTURE.md](docs/ARCHITECTURE.md) - Code organization and structure\n- [USAGE.md](docs/USAGE.md) - Detailed usage examples\n- [STREAMING.md](docs/STREAMING.md) - Streaming responses guide\n- [CUSTOM_TOOLS_GUIDE.md](docs/CUSTOM_TOOLS_GUIDE.md) - Creating custom tools\n- [RAG_GUIDE.md](docs/RAG_GUIDE.md) - RAG implementation details\n- [PUBLISHING.md](docs/PUBLISHING.md) - NPM publishing and release process\n\n## Troubleshooting\n\n**Cannot connect to Ollama** - Ensure `ollama serve` is running  \n**Model not found** - Run `ollama pull <model-name>` first  \n**Workflow file not found** - Check file path is correct\n\n## Contributing\n\nContributions welcome! Submit a Pull Request.\n\n## License\n\nISC","readmeFilename":"README.md"}