{"id":13494837,"url":"https://github.com/nooqta/saiku","last_synced_at":"2025-10-25T11:30:48.438Z","repository":{"id":197563124,"uuid":"698909249","full_name":"nooqta/saiku","owner":"nooqta","description":"AI Agent capable of automating various tasks using openai function call feature","archived":false,"fork":false,"pushed_at":"2023-11-28T07:18:34.000Z","size":13635,"stargazers_count":34,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-31T07:03:07.412Z","etag":null,"topics":["agent","ai","automation","dalle3","huggingface","ollama","openai","openai-api","openai-vision","speech-to-text","text-to-speech","vertex-ai"],"latest_commit_sha":null,"homepage":"https://noqta.mintlify.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nooqta.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"Contributing.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":["anis-marrouchi"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2023-10-01T11:00:20.000Z","updated_at":"2025-01-24T13:25:04.000Z","dependencies_parsed_at":"2023-11-26T15:12:41.340Z","dependency_job_id":null,"html_url":"https://github.com/nooqta/saiku","commit_stats":null,"previous_names":["nooqta/agent","nooqta/saiku"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nooqta%2Fsaiku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nooqta%2Fsaiku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nooqta%2Fsaiku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nooqta%2Fsaiku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nooqta","download_url":"https://codeload.github.com/nooqta/saiku/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238128492,"owners_count":19421045,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","automation","dalle3","huggingface","ollama","openai","openai-api","openai-vision","speech-to-text","text-to-speech","vertex-ai"],"created_at":"2024-07-31T19:01:28.732Z","updated_at":"2025-10-25T11:30:48.425Z","avatar_url":"https://github.com/nooqta.png","language":"TypeScript","funding_links":["https://github.com/sponsors/anis-marrouchi"],"categories":["TypeScript"],"sub_categories":[],"readme":"# Saiku (細工) The AI Agent\n\u003cb\u003e\u003ca href=\"https://noqta.mintlify.app/\"\u003eRead our documentation\u003c/a\u003e\u003c/b\u003e\n\nLooking for the Python version? Check out [Saiku.py](https://github.com/anis-marrouchi/saiku.py).\n\n## Table of Contents\n\n- [About](#about)\n  - [Core Architecture: Model Context Protocol (MCP)](#core-architecture-model-context-protocol-mcp)\n  - [Why Saiku?](#why-saiku)\n  - [What is PEAS?](#what-is-peas)\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n  - [Optional Requirements](#optional-requirements)\n- [1. Using Saiku in Your Own Projects](#1-using-saiku-in-your-own-projects)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [Importing Saiku](#importing-saiku)\n    - [Initializing Saiku Agent](#initializing-saiku-agent)\n    - [Configuring Saiku](#configuring-saiku)\n    - [Interacting with Saiku](#interacting-with-saiku)\n- [2. Using the Project Itself](#2-using-the-project-itself)\n  - [Usage](#usage-1)\n    - [Clone the Repository](#clone-the-repository)\n    - [Navigate to Project Folder](#navigate-to-project-folder)\n    - [Install Dependencies](#install-dependencies)\n    - [Run the Project Locally](#run-the-project-locally)\n- [3. Global Installation (Not Recommended Yet)](#3-global-installation-not-recommended-yet)\n- [Demo](#demo)\n- [Setting Up Environment Variables](#setting-up-environment-variables)\n- [Available Commands](#available-commands)\n  - [Examples](#examples)\n- [Use Cases (via MCP \u0026 Extensions)](#use-cases-via-mcp--extensions)\n- [Workflows](#workflows)\n- [Future Features](#future-features)\n- [Contributing](#contributing)\n- [Support Saiku](#support-saiku)\n- [Feedback and Issues](#feedback-and-issues)\n- [API Rate Limits/Cost](#api-rate-limitscost)\n- [Note](#note)\n- [License](#license)\n\n## About\n\nThis project aims to create a robust, intelligent AI Agent capable of automating various tasks. Our agent is designed following the PEAS (Performance measure, Environment, Actuators, Sensors) framework to ensure it's robust, scalable, and efficient.\n\n### Core Architecture: Model Context Protocol (MCP)\n\nSaiku leverages the **Model Context Protocol (MCP)**, a cutting-edge standard for enabling AI models to interact with external tools and resources securely and efficiently. MCP is becoming increasingly vital in the AI landscape, allowing agents like Saiku to:\n\n*   **Extend Capabilities:** Seamlessly integrate with various tools (filesystem access, web browsing, API interactions, code execution, etc.) provided by connected MCP servers.\n*   **Access Real-time Data:** Utilize dynamic information from connected resources (e.g., databases, APIs, system information).\n*   **Perform Complex Actions:** Go beyond text generation to execute commands, manipulate files, interact with external systems, and orchestrate multi-step processes.\n\nBy building on MCP, Saiku ensures a flexible, extensible, and future-proof architecture for AI agent development. Learn more about MCP [here](./documentation/MCP.md).\n\n### Why Saiku?\n\n\"Saiku\" (細工) in Japanese refers to detailed or delicate work, symbolizing the intricate and intelligent workings of our AI agent.\n\n- **S**: Smart\n- **A**: Artificial\n- **I**: Intelligent\n- **K**: Knowledgeable\n- **U**: Unmatched\n\nWe chose a Japanese name to symbolize precision, innovation, and advanced technology, attributes highly respected in Japanese culture. Even though we are based in Tunisia, we believe in global collaboration and the universal appeal and understanding of technology.\n\n### What is PEAS?\n\nPEAS stands for Performance measure, Environment, Actuators, and Sensors. It's a framework used to describe the various components of an intelligent agent:\n\n- **Performance Measure**: How well is the agent doing in its environment? (e.g., task completion rate, efficiency)\n- **Environment**: Where the agent operates (e.g., user's local machine, specific software, web)\n- **Actuators**: What actions the agent can take via MCP tools (e.g., writing files, executing commands, calling APIs)\n- **Sensors**: How the agent perceives its environment via MCP resources and tool outputs (e.g., reading files, getting system status, receiving API responses)\n\n## Features\n\n- **MCP-Powered:** Core architecture based on the Model Context Protocol for secure and extensible tool/resource integration.\n- **Multi-LLM Support:** Integrates with various Large Language Models (OpenAI, Vertex AI, Ollama, Hugging Face, Mistral, Anthropic).\n- **Workflow Engine:** Define and run complex, multi-step automations using JSON-based workflows.\n- **Extensible:** Easily add new capabilities by connecting new MCP servers.\n- **VS Code Extension:** Interact with Saiku using voice commands directly within your editor via the [Cline Voice Assistant extension](./extensions/cline-voice-assistant/).\n- **Web Interface:** Chat with Saiku through a browser interface.\n\n## Prerequisites\n\n- **Node.js:** Version 18 or higher recommended.\n- **LLM API Key:** An API key for at least one supported Large Language Model (e.g., OpenAI).\n\n### Optional Requirements\n\n- **MCP Servers:** For extended capabilities (like file system access, web browsing, code execution, specific API interactions, text-to-speech, speech-to-text), you need to run the corresponding MCP servers. Many servers require their own API keys or setup (e.g., ElevenLabs API key for TTS/STT, Google Cloud credentials for Vision/Calendar). Configure these in your MCP settings.\n- **Git:** Required for using git-related MCP tools.\n\n## 1. Using Saiku in Your Own Projects\nSaiku can be integrated into your applications to leverage its agent capabilities.\n\n### Installation\n\n- **Step**: Run ```npm install saiku``` in your project directory.\n\n### Usage\n\n#### 1. Importing Saiku\n\n- **Code**:\n  ```javascript\n  import Agent from 'saiku';\n  // Or specific components if needed\n  ```\n\n#### 2. Initializing Saiku Agent\n\n- **Example**:\n  ```javascript\n  async function main(opts) {\n    // Ensure MCP client/server setup is handled appropriately\n    const agent = new Agent(opts); // Initialize the agent\n    // ...\n  }\n  ```\n\n#### 3. Configuring Saiku\n\n- **AgentOptions**:\n  - **systemMessage** (`string` | `optional`): Default system message or instructions for the LLM.\n  - **allowCodeExecution** (`boolean` | `optional`): Flag to enable/disable code execution (typically handled by a dedicated MCP server now).\n  - **interactive** (`boolean` | `string` | `optional`): Interactive mode setting for CLI usage.\n  - **llm** (`'openai' | 'vertexai' | 'ollama' | 'huggingface' | 'mistral' | 'anthropic'`): Specifies the language learning model. Default is `'openai'`.\n  - **[key: string]: any** (`optional`): Allows additional custom properties.\n\n- **Example Configuration**:\n  ```javascript\n  let opts = {\n    systemMessage: \"You are Saiku, an AI assistant.\",\n    interactive: true,\n    llm: \"openai\",\n    // Custom options\n  };\n  ```\n\n#### 4. Interacting with Saiku\n\n- **Process**:\n  - **User Input**: Provide user queries or tasks.\n  - **MCP Interaction**: The agent interacts with connected MCP servers to use tools and access resources based on the query.\n  - **Response Generation**: Generates responses based on LLM processing and tool results.\n\n- **Example Interaction**:\n  ```javascript\n  // Assuming 'agent' is an initialized Agent instance\n  async function runInteraction(agent, userQuery) {\n    agent.messages.push({ role: \"user\", content: userQuery });\n    await agent.interact(); // Agent processes query, potentially using MCP tools\n    // Handle agent's response (last message in agent.messages)\n  }\n  ```\n\n## 2. Using the project itself\n### Usage\n- **Clone the Repository**:\n  ```bash\n  git clone https://github.com/nooqta/saiku.git\n  ```\n\n- **Navigate to Project Folder**:\n  ```bash\n  cd saiku\n  ```\n\n- **Install Dependencies**:\n  ```bash\n  npm install\n  ```\n\n\n- **Run the Project Locally**:\n\nBefore starting Saiku locally, build the project:\n```bash\nnpm run build\n```\n\nTo start the agent in interactive CLI mode:\n```bash\nnpm start\n```\n\nFor automated building during development:\n```bash\nnpm run watch\n```\n\n## 3. Global Installation (Not Recommended Yet)\n\nGlobal installation is possible but not recommended due to ongoing development.\n```bash\nnpm install -g saiku\n```\n\n## Demo\n\nhttps://github.com/nooqta/saiku/assets/3036133/87752826-fc6a-4c16-91a7-917b0f79427a\n\n### A Jupyter notebook available on Google Colab:\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/nooqta/saiku/blob/main/saiku-demo-notebook.ipynb) (Note: May require updates for MCP compatibility)\n\n## Setting Up Environment Variables\n\nConfigure necessary environment variables for the core agent and any MCP servers you intend to use. Copy the example environment file:\n```bash\ncp .env.example .env\n```\n\nEdit the `.env` file. Minimally, you need an LLM API key:\n```dotenv\n# OpenAI (Example)\nOPENAI_API_KEY=your_openai_api_key\nOPENAI_MODEL=gpt-4-turbo # Or another model\n\n# Add other API keys as needed for specific MCP servers\n# e.g., ELEVENLABS_API_KEY=... for the ElevenLabs MCP server\n# e.g., GOOGLE_APPLICATION_CREDENTIALS=path/to/your/keyfile.json for Google Cloud servers\n```\nRefer to the documentation of individual MCP servers for their specific environment variable requirements.\n\n## Available Commands\n\nUse the Saiku CLI with various options:\n```\nAI agent to help automate your tasks\n\nOptions:\n  -v, --version                Output the current version.\n  -exec, --allowCodeExecution  (Deprecated - Handled by MCP) Execute code without prompting.\n  -role, --systemMessage       The model system role message.\n  -m, --llm \u003cmodel\u003e            Specify the language model (openai, vertexai, ollama, huggingface, mistral, anthropic). Default: openai.\n  -h, --help                   Display help for command.\n\nCommands:\n  mcp [options]                Manage MCP servers.\n  workflow [options]           Manage and run workflows.\n  autopilot [options]          (Experimental) Run Saiku in autopilot mode.\n  serve                        Chat with the Saiku agent in the browser.\n  help [command]               Display help for a specific command.\n```\n\n#### Examples:\n\nTo start the interactive CLI with a specific LLM:\n```bash\nnpm start -- -m ollama\n```\n\nTo run a specific workflow:\n```bash\nnpm start -- workflow run \u003cworkflow_name\u003e\n```\n\nTo list connected MCP servers:\n```bash\nnpm start -- mcp list\n```\n\nTo chat with Saiku in the browser:\n```bash\nnpm start -- serve\n```\n\n## Use Cases (via MCP \u0026 Extensions)\n\nSaiku achieves tasks by leveraging tools provided by connected MCP servers or through specific extensions.\n\n- **Transcribe Audio to Text:** Use an STT MCP server (e.g., ElevenLabs, Whisper) to transcribe audio files.\n- **Extract Text from Image:** Use a Vision MCP server (e.g., Google Vision) to perform OCR on images.\n- **Summarize Long Articles:** The core LLM can summarize provided text, potentially fetched via a Filesystem or HTTP MCP server.\n- **HTML to PDF Conversion:** Use a Puppeteer or similar MCP server with HTML-to-PDF capabilities.\n- **Take Screenshot of Webpage:** Use a Puppeteer MCP server.\n- **Text to Speech:** Use a TTS MCP server (e.g., ElevenLabs).\n- **File Actions (Read/Write/List):** Use a Filesystem MCP server.\n- **Database Queries:** Use a custom MCP server connected to your database.\n- **Git Operations:** Use a Git MCP server.\n- **API Interactions (GitLab, GitHub, etc.):** Use specific MCP servers designed for those APIs.\n- **Voice Interaction:** Use the VS Code Cline Voice Assistant extension, which coordinates with STT/TTS MCP servers.\n\n## Workflows\n\nSaiku includes a workflow engine that allows you to define complex, multi-step tasks in a JSON format. These workflows can chain together multiple LLM calls and MCP tool uses to automate sophisticated processes.\n\n- **Define:** Create workflow JSON files (see `workflows.json` for examples).\n- **List:** ```npm start -- workflow list```\n- **Run:** ```npm start -- workflow run \u003cworkflow_name\u003e [input_data]```\n\n## Future Features\n\n- **Enhanced Workflow Engine**: More complex logic, error handling, and dynamic step generation in workflows.\n- **Improved MCP Server Management**: Easier discovery, installation, and configuration of MCP servers.\n- **Multi-Agent Collaboration**: Exploring scenarios where multiple Saiku agents (or other MCP-compatible agents) can collaborate.\n- **Advanced Memory/Context Management**: More sophisticated techniques for handling long-running tasks and large contexts.\n- **Proactive Assistance**: Developing capabilities for the agent to suggest actions or workflows proactively.\n- **Refined PEAS Implementation**: Continuously improving how the agent senses its environment and acts within it via MCP.\n- **Comprehensive Tests**: Expanding test coverage for core agent logic, MCP interactions, and workflows.\n- **Cost Tracking \u0026 Budgeting**: Integrating better mechanisms for tracking and managing API costs.\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create your feature branch (```git checkout -b feature/YourFeature```)\n3. Commit your changes (```git commit -m 'Add some feature'```)\n4. Push to the branch (```git push origin feature/YourFeature```)\n5. Create a new Pull Request\n\nSee [Contributing Guidelines](CONTRIBUTING.md).\n\n## Support Saiku\n\nWe are actively seeking sponsors and contributors. Your support helps accelerate development.\n\n## Feedback and Issues\n\nPlease open an issue on our GitHub repository for feedback or bug reports.\n\n## API Rate Limits/Cost\n\nBe mindful of the rate limits and costs associated with the LLM APIs and any external services used by MCP servers.\n\n## Note\n\nSaiku is under active development. Expect changes to the architecture and features.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnooqta%2Fsaiku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnooqta%2Fsaiku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnooqta%2Fsaiku/lists"}