{"_id":"@berkayz/openflow","name":"@berkayz/openflow","dist-tags":{"prerelease":"0.0.1-pre-alpha","latest":"0.0.1-pre-alpha"},"versions":{"0.0.1-pre-alpha":{"name":"@berkayz/openflow","version":"0.0.1-pre-alpha","description":"Open protocol for AI LLM flow development (Under development)","keywords":["ai","llm","workflow","automation","typescript","flow","protocol"],"homepage":"https://github.com/berkayz/openflow-nodejs-sdk#readme","bugs":{"url":"https://github.com/berkayz/openflow-nodejs-sdk/issues"},"repository":{"type":"git","url":"git+https://github.com/BerkayZ/openflow-nodejs-sdk.git"},"license":"GPL-3.0-or-later","author":{"name":"Berkay Zelyurt","email":"zelyurtberkay@gmail.com"},"type":"commonjs","main":"dist/index.js","types":"dist/index.d.ts","bin":{"openflow":"dist/cli.js"},"directories":{"example":"examples","test":"tests"},"scripts":{"build":"tsc","dev":"tsc --watch","test":"jest","test:unit":"jest --selectProjects \"Unit Tests\"","test:integration":"jest --selectProjects \"Integration Tests\"","test:watch":"jest --watch","test:coverage":"jest --coverage","test:verbose":"jest --verbose","test:silent":"jest --silent","test:ci":"jest --ci --coverage --watchAll=false","lint":"eslint . --ext .ts,.js --fix","format":"prettier --write \"**/*.{ts,js,json,md}\"","clean":"rimraf dist/ coverage/ test-reports/ .jest-cache/","prepare":"npm run build","prepack":"npm run build","validate":"npm run lint && npm run test:ci","docs":"typedoc --out docs src/index.ts","example:01":"npx ts-node examples/01-basic-llm.ts","example:02":"npx ts-node examples/02-conditional-logic.ts","example:03":"npx ts-node examples/03-for-each-loop.ts","example:04":"npx ts-node examples/04-image-analysis.ts","example:05":"npx ts-node examples/05-pdf-processing.ts","example:06":"npx ts-node examples/06-embed-and-store.ts","example:07":"npx ts-node examples/07-vector-search.ts","example:08":"npx ts-node examples/08-hooks-example.ts","example:09":"npx ts-node examples/09-mcp-deepwiki.ts","example:10":"npx ts-node examples/10-mcp-semgrep.ts","example:11":"npx ts-node examples/11-mcp-coingecko.ts","example:12":"npx ts-node examples/12-rag-chat.ts","example:13":"npx ts-node examples/13-document-chat.ts"},"dependencies":{"@pinecone-database/pinecone":"^6.1.1","@types/uuid":"^10.0.0","axios":"^1.6.7","dotenv":"^16.4.1","pdf2image":"^1.2.3","sharp":"^0.33.5","uuid":"^11.1.0"},"devDependencies":{"@types/jest":"^29.5.14","@types/node":"^20.11.17","@typescript-eslint/eslint-plugin":"^6.21.0","@typescript-eslint/parser":"^6.21.0","eslint":"^8.56.0","eslint-config-prettier":"^9.1.0","eslint-plugin-prettier":"^5.5.1","jest":"^29.7.0","jest-html-reporters":"^3.1.7","jest-junit":"^16.0.0","prettier":"^3.2.5","rimraf":"^5.0.5","ts-jest":"^29.4.0","ts-node":"^10.9.2","tsx":"^4.20.3","typedoc":"^0.25.13","typescript":"^5.3.3"},"peerDependencies":{"typescript":">=4.5.0"},"optionalDependencies":{"canvas":"^2.11.2"},"engines":{"node":">=18.0.0","npm":">=8.0.0"},"licenses":[{"type":"GPL-3.0-or-later","url":"https://www.gnu.org/licenses/gpl-3.0.en.html"}],"_id":"@berkayz/openflow@0.0.1-pre-alpha","gitHead":"0a58c4fe15ec62d190ac8870c224db5c3b002633","_nodeVersion":"24.7.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-Qc4WqoHQQ3/T2oX3DwPAjdMLgPP6hLPW+xGhHbBYunOFBEEP0HSDU6WqUMLqhpqiNn+oCcHfnDle1m+WWkhNUQ==","shasum":"1683acaa4e05f6eeaac88bc451e036befcd1b989","tarball":"https://registry.npmjs.org/@berkayz/openflow/-/openflow-0.0.1-pre-alpha.tgz","fileCount":62,"unpackedSize":480104,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIC48hhPGKFvzWD0HCwn4nKZKuSL7vRA9ijqaSr9UQ9xJAiEA2t8yFtsn3L7MML9hhrdS9nIvMsk5LZ3hjhYkt9zXJCQ="}]},"_npmUser":{"name":"berkayz","email":"zelyurtberkay@gmail.com"},"maintainers":[{"name":"berkayz","email":"zelyurtberkay@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openflow_0.0.1-pre-alpha_1763851703434_0.6806735016478009"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-22T22:48:23.332Z","0.0.1-pre-alpha":"2025-11-22T22:48:23.672Z","modified":"2025-11-22T22:48:23.971Z"},"maintainers":[{"name":"berkayz","email":"zelyurtberkay@gmail.com"}],"description":"Open protocol for AI LLM flow development (Under development)","homepage":"https://github.com/berkayz/openflow-nodejs-sdk#readme","keywords":["ai","llm","workflow","automation","typescript","flow","protocol"],"repository":{"type":"git","url":"git+https://github.com/BerkayZ/openflow-nodejs-sdk.git"},"author":{"name":"Berkay Zelyurt","email":"zelyurtberkay@gmail.com"},"bugs":{"url":"https://github.com/berkayz/openflow-nodejs-sdk/issues"},"license":"GPL-3.0-or-later","readme":"# OpenFlow Node.js SDK\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Development Status](https://img.shields.io/badge/Status-Under%20Development-yellow.svg)](https://github.com/berkayz/openflow-nodejs-sdk)\n![Stage: Pre-Alpha](https://img.shields.io/badge/Stage-Pre_Alpha-purple.svg)\n\n> **⚠️ NOTICE: This package is currently under active development and is not fully complete. APIs may change without notice. Use at your own risk for production applications.**\n\nThe **OpenFlow Node.js SDK** is a TypeScript/JavaScript implementation of the OpenFlow Protocol — a standardized, extensible, and model-agnostic specification for orchestrating AI workflows using structured JSON definitions.\n\n## 🚀 What is OpenFlow?\n\nOpenFlow enables you to build complex AI workflows by chaining together different types of nodes:\n\n- **LLM Nodes**: Generate text, analyze images, process documents\n- **Vector Database Nodes**: Store and search embeddings (Pinecone support)\n- **Document Processing**: Split PDFs into pages, extract text and images\n- **Control Flow**: Conditional logic, loops, variable manipulation\n- **Embedding Nodes**: Generate text embeddings (OpenAI support)\n- **MCP Integration**: Model Context Protocol support for external tools and data sources\n\nAll orchestrated through declarative JSON flows that are portable, inspectable, and scalable.\n\n## 📋 Current Status\n\n### ✅ Implemented Features\n\n- **Core Execution Engine**: Flow validation, execution, and variable resolution\n- **LLM Integration**: Grok and OpenAI with text and vision support\n- **Vector Database**: Pinecone integration (insert, search)\n- **Document Processing**: PDF to image conversion and analysis\n- **Text Embeddings**: OpenAI text-embedding models\n- **Control Flow**: FOR_EACH loops, conditional branching, variable updates\n- **Input Variables**: Runtime variable passing with type support\n- **MCP Integration**: Model Context Protocol support with real-time tool access\n- **Comprehensive Examples**: 12 working examples covering all features\n- **Execution Hooks**: Pre/post execution hooks for custom logic\n\n### 🚧 In Development\n\n- **Additional LLM Providers**: AWS Bedrock, Anthropic, Gemini\n- **More Vector Databases**: Weaviate, Qdrant, Chroma\n- **Generative AI Nodes**: Image generation, audio processing, video generation\n- **Plugin System**: Custom node types and providers\n- **Performance Optimizations**: Caching, connection pooling\n\n### 🔮 Planned Features\n\n- **Stream Support**: Real-time data processing and streaming nodes\n- **CLI Tools**: Flow execution and validation commands\n- **Web Interface**: Visual flow builder and monitoring\n- **Flow Marketplace**: Share and discover community flows\n- **Plugin System**: Custom node types and providers\n- **Cloud Deployment**: Hosted execution environment\n- **Real-time Monitoring**: Flow execution dashboards\n- **Local Models**: Support for running models locally (e.g., Llama 3, Mistral)\n\n## 🛠️ Installation\n\n```bash\nwill published in alpha version\n```\n\n## 🚀 Quick Start\n\n```typescript\n// Configure the executor\nconst executor = new FlowExecutor({\n  concurrency: {\n    global_limit: 3,\n  },\n  providers: {\n    llm: {\n      grok: {\n        apiKey: \"your_grok_api_key\",\n      },\n    },\n  },\n  logLevel: \"info\",\n});\n\n// Define a simple flow\nconst flow = {\n  name: \"hello-world\",\n  version: \"1.0.0\",\n  description: \"A simple greeting flow\",\n  author: \"Your Name\",\n  variables: [\n    {\n      id: \"user_name\",\n      type: \"string\",\n    },\n  ],\n  input: [\"user_name\"],\n  output: [\"greeting\"],\n  nodes: [\n    {\n      id: \"greet\",\n      type: \"LLM\",\n      name: \"Generate Greeting\",\n      config: {\n        provider: \"grok\",\n        model: \"grok-3-latest\",\n        max_tokens: 100,\n      },\n      messages: [\n        {\n          type: \"text\",\n          role: \"user\",\n          text: \"Generate a friendly greeting for {{user_name}}\",\n        },\n      ],\n      output: {\n        greeting: {\n          type: \"string\",\n          description: \"A friendly greeting message\",\n        },\n      },\n    },\n  ],\n};\n\n// Execute the flow\nconst result = await executor.executeFlow(flow, {\n  user_name: \"Alice\",\n});\n\nconsole.log(result.outputs.greeting);\n```\n\n## 📚 Examples\n\nThe SDK includes examples in the `/examples` directory:\n\n- **01-basic-llm.ts**: Basic LLM text generation\n- **02-conditional-logic.ts**: Conditional branching based on user scores\n- **03-for-each-loop.ts**: Array processing with FOR_EACH loops\n- **04-image-analysis.ts**: Image analysis using vision models\n- **05-pdf-processing.ts**: PDF document processing and analysis\n- **06-embed-and-store.ts**: Generate embeddings and store in vector database\n- **07-vector-search.ts**: Semantic search using vector similarity\n- **08-hooks-example.ts**: Flow execution hooks and lifecycle management\n- **09-mcp-deepwiki.ts**: MCP integration with DeepWiki knowledge search\n- **10-mcp-semgrep.ts**: MCP integration with Semgrep security scanning\n- **11-mcp-coingecko.ts**: MCP integration with CoinGecko cryptocurrency data\n\nRun any example:\n\n```bash\nnpm run example:01\n```\n\n## 🏗️ Architecture\n\n### Core Components\n\n- **FlowExecutor**: Main execution engine with concurrency control\n- **Node Types**: Specialized processors for different AI tasks\n- **Variable System**: Dynamic variable resolution and scoping\n- **FileManager**: Secure file handling and temporary storage\n- **Provider System**: Pluggable integrations for external services\n- **Validation Engine**: Schema validation and dependency analysis\n\n### Flow Structure\n\n```json\n{\n  \"name\": \"my-flow\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Example flow\",\n  \"author\": \"Your Name\",\n  \"variables\": [\n    {\n      \"id\": \"input_text\",\n      \"type\": \"string\"\n    }\n  ],\n  \"input\": [\"input_text\"],\n  \"output\": [\"result\"],\n  \"nodes\": [\n    // Array of processing nodes\n  ]\n}\n```\n\n## 🔧 Configuration\n\n### MCP Integration\n\nThe SDK supports Model Context Protocol (MCP) integration, allowing LLMs to access external tools and data sources in real-time even model is not supporting MCP natively. This enables advanced capabilities like knowledge search, security scanning, and more.:\n\n```typescript\nconst flow = {\n  nodes: [\n    {\n      id: \"llm_with_mcp\",\n      type: \"LLM\",\n      name: \"LLM with MCP Tools\",\n      config: {\n        provider: \"grok\",\n        model: \"grok-3-latest\",\n        // MCP server configurations\n        mcp_servers: [\n          {\n            name: \"deepwiki\",\n            url: \"https://mcp.deepwiki.com/mcp\",\n            description: \"DeepWiki knowledge search\",\n            auth: { type: \"none\" },\n          },\n          {\n            name: \"semgrep\",\n            url: \"https://mcp.semgrep.ai/mcp\",\n            description: \"Semgrep security scanning\",\n            auth: { type: \"none\" },\n          },\n        ],\n        // MCP tools configuration\n        tools: {\n          auto_discover: true,\n          mcp_servers: [\"deepwiki\", \"semgrep\"],\n          builtin_tools: [\"set_variable\", \"get_variable\"],\n        },\n      },\n      messages: [\n        {\n          type: \"text\",\n          role: \"system\",\n          text: \"You have access to external tools. Use them to enhance your responses.\",\n        },\n      ],\n    },\n  ],\n};\n```\n\n### Provider Setup\n\n```typescript\nconst config = {\n  providers: {\n    llm: {\n      grok: {\n        apiKey: \"your_grok_api_key\",\n      },\n    },\n    vectorDB: {\n      pinecone: {\n        provider: \"pinecone\",\n        index_name: \"your-index\",\n        apiKey: \"your_pinecone_api_key\",\n      },\n    },\n    embeddings: {\n      openai: {\n        apiKey: \"your_openai_api_key\",\n      },\n    },\n  },\n};\n```\n\n## 📖 Documentation\n\n- **[Protocol Specification](https://protocol.openflowsdk.org)**: Complete OpenFlow protocol documentation\n- **[Examples README](./examples/README.md)**: Detailed example documentation\n\n## 🤝 Contributing\n\nWe welcome contributions! Since the project is under active development, please:\n\n1. Check existing issues and discussions\n2. Open an issue before starting major work\n3. Follow the existing code style and patterns\n4. **Run linting and formatting** before submitting:\n   ```bash\n   npm run lint    # Check and fix linting issues\n   npm run format  # Format code with Prettier\n   npm run validate # Run both linting and tests\n   ```\n5. **Minimize external dependencies** - avoid adding new libraries unless absolutely necessary. If you need to add a dependency, discuss it in an issue first\n6. Include tests for new features, develop with test driven development (TDD)\n7. Update documentation as needed\n\n## Testing Requirements\n\n**⚠️ API Keys Required for Testing**\n\nMost tests require valid API keys to function properly.\n\\\nExample env file is .env.test.example.\n\\\nThe test suite includes both unit and integration tests:\n\n- **Unit Tests**: Test core logic without external API calls\n- **Integration Tests**: Test actual provider integrations (require API keys)\n\n### Required API Keys:\n\n1. **Grok API Key** - For LLM integration tests\n   - Get from: [console.x.ai](https://console.x.ai)\n   - Required for: LLM node tests, MCP integration tests\n\n2. **OpenAI API Key** - For embeddings and alternative LLM tests\n   - Get from: [platform.openai.com](https://platform.openai.com)\n   - Required for: Embedding tests, OpenAI LLM tests\n\n3. **Pinecone API Key** - For vector database tests\n   - Get from: [pinecone.io](https://pinecone.io)\n   - Required for: Vector database integration tests\n   - **Note**: You'll also need to create a test index in Pinecone\n\n### Running Tests:\n\n```bash\n# Run all tests (requires API keys)\nnpm test\n\n# Run only unit tests (no API keys needed)\nnpm run test:unit\n\n# Run integration tests (requires API keys)\nnpm run test:integration\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run tests in CI mode\nnpm run test:ci\n```\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/berkayz/openflow-nodejs-sdk.git\ncd openflow-nodejs-sdk\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run linting and formatting\nnpm run lint\nnpm run format\n\n# Run the validation suite (lint + tests)\nnpm run validate\n\n# Run examples\nnpm run example:01\n```\n\n**Code Quality:**\n\n- We use ESLint for linting and Prettier for formatting\n- Run `npm run validate` before committing to ensure code quality\n- All code should pass linting without warnings\n- Follow TypeScript best practices\n\n## 📝 License\n\nThis project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See the [LICENSE](./LICENSE) file for details.\n\n---\n\n**Built with ❤️ for AI community by [Berkay Zelyurt](https://github.com/berkayz)**\n","readmeFilename":"README.md","_rev":"1-2a7225da4d1a95a06249a41b93d71ddb"}