{"id":27317077,"url":"https://github.com/iotexproject/quicksilver","last_synced_at":"2025-04-12T08:52:56.251Z","repository":{"id":270881630,"uuid":"911725450","full_name":"iotexproject/quicksilver","owner":"iotexproject","description":"an open-source framework that bridges the capabilities of Large Language Models (LLMs) with Decentralized Physical Infrastructure Networks (DePINs) to create advanced AI agents.","archived":false,"fork":false,"pushed_at":"2025-04-03T11:49:01.000Z","size":9049,"stargazers_count":30,"open_issues_count":6,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-12T08:52:50.304Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iotexproject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-03T17:40:19.000Z","updated_at":"2025-04-03T11:49:01.000Z","dependencies_parsed_at":"2025-02-13T18:22:18.447Z","dependency_job_id":"17ab8c28-63cb-4695-9fbb-68776b6aaa4d","html_url":"https://github.com/iotexproject/quicksilver","commit_stats":null,"previous_names":["raullenchai/quicksilver","iotexproject/quicksilver"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iotexproject%2Fquicksilver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iotexproject%2Fquicksilver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iotexproject%2Fquicksilver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iotexproject%2Fquicksilver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iotexproject","download_url":"https://codeload.github.com/iotexproject/quicksilver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248543882,"owners_count":21121838,"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":[],"created_at":"2025-04-12T08:52:55.663Z","updated_at":"2025-04-12T08:52:56.238Z","avatar_url":"https://github.com/iotexproject.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quicksilver: Sentient AI Framework\n\n[![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=flat\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![GitHub last commit](https://img.shields.io/github/last-commit/raullenchai/quicksilver)](https://github.com/raullenchai/quicksilver/commits/main)\n[![GitHub stars](https://img.shields.io/github/stars/raullenchai/quicksilver?style=social)](https://github.com/raullenchai/quicksilver/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/raullenchai/quicksilver?style=social)](https://github.com/raullenchai/quicksilver/network/members)\n\n**Quicksilver** is an open-source framework that bridges the capabilities of **Large Language Models (LLMs)** with **Decentralized Physical Infrastructure Networks (DePINs)** to create **advanced AI agents**.\n\n\u003e By leveraging DePINs as the \"_sensorial component_\", Quicksilver enables AI agents to interact with the physical world, gather real-time data, and respond contextually.\n\n\u003cdetails\u003e\n  \u003csummary\u003eRead more\u003c/summary\u003e\nThe QuickSilver framework empowers developers to build intelligent agents that:\n\n- **Sense and Understand**: Use DePINs to collect and process data from decentralized physical infrastructure, acting as the sensory layer for AI agents.\n- **Act and Respond**: Combine LLMs' advanced reasoning capabilities with data from DePINs to perform context-aware interactions.\n- **Integrate Seamlessly**: Utilize the framework's modularity to connect with multiple DePIN projects, including weather, energy, and location networks, enabling agents to access diverse sources of decentralized data.\n- **Orchestrate Workflows**: Automate multi-step processes while maintaining state and context.\n\n\u003c/details\u003e\n\n---\n\n![Preview](./assets/preview.gif)\n\n## Features\n\n- **Workflow Orchestration**: Executes complex, multi-step tasks orchestrating interaction between LLM, tools, and memory.\n- **LLM Integration**: Suports popular LLMs like OpenAI, Gemini, etc... to understand and generate human-like text.\n- **Contextual Memory**: Maintains state and context across conversations.\n- **Built in Tools**: Built-in tools for computing, interacting with DePIN projects and other APIs (e.g., weather and energy data, news services, and more).\n- **Modular Architecture**: Easily extendable with new tools and workflows.\n\n---\n\n## Architecture\n\nQuicksilver's architecture is modular and extensible, enabling developers to customize it for various use cases.\n\n```mermaid\ngraph TD\n    A[Sentient AI - Core Orchestrator]\n    B[Contextual Memory]\n    C[Workflow Manager]\n    D[Modular Tools]\n    E[LLM Integration]\n    F[Energy DePIN Data]\n    G[News API]\n    H[Weather DePIN Data]\n    I[Custom Tool...]\n\n\n    A \u003c--\u003e B\n    A --\u003e C\n    C --\u003e E\n    C --\u003e D\n    D --\u003e F\n    D --\u003e G\n    D --\u003e I\n    D --\u003e H\n    E --\u003e A\n```\n\n### Key Components\n\n1. **Sentient AI (Core Orchestrator)**: Central hub managing interactions and delegating tasks.\n2. **Contextual Memory**: Tracks user interactions and maintains context for continuity. This has been removed to make API calls more efficient.\n3. **Workflow Manager**: Handles task automation and orchestration.\n4. **Modular Tools**: Extensible modues for interacting with different DePINs.\n5. **LLM Integration**: Interfaces with language models for intelligent responses.\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) (v22)\n- [bun](https://bun.sh/)\n- Docker (optional, for containerized environments)\n\n### Installation\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/iotexproject/quicksilver.git\n   cd quicksilver\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   bun i\n   ```\n\n3. Create a `.env` file based on `.env.template`:\n\n   ```env\n    OPENAI_API_KEY=your_openai_api_key\n    NUBILA_API_KEY=your_nubila_api_key\n    NEWSAPI_API_KEY=your_newsapi_api_key\n   ```\n\n4. Run example agents:\n\nSome example agents are located in the `example` folder. Run an example with:\n\n```bash\nbun run example/demo_agent.ts\n```\n\n5. Run the server:\n\n   ```bash\n   bun run start\n   ```\n\n6. Test API query:\n\n   ```bash\n    curl http://localhost:8000/ask -X POST -H \"Content-Type: application/json\" -d '{\"q\": \"What is the weather in San Francisco?\"}'\n   ```\n\n7. Access raw tool data:\n\n   ```bash\n   # Get raw weather data for San Francisco\n   curl \"http://localhost:8000/raw?tool=weather-current\u0026lat=37.7749\u0026lon=-122.4194\"\n\n   # Get raw news data\n   curl \"http://localhost:8000/raw?tool=news\"\n\n   # Get raw DePIN metrics\n   curl \"http://localhost:8000/raw?tool=depin-metrics\u0026isLatest=true\"\n   ```\n\nThe `/raw` endpoint allows direct access to tool data without LLM processing. This is useful for:\n\n- Debugging tool responses\n- Building custom integrations\n- Reducing API costs by skipping LLM processing\n- Accessing structured data formats\n- Context providing for agents\n\nAvailable tools and their parameters:\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `weather-current` | `lat`, `lon` | Current weather data |\n| `weather-forecast` | `lat`, `lon` | Weather forecast |\n| `news` | none | Latest news headlines |\n| `depin-metrics` | `isLatest` | DePIN network metrics |\n| `depin-projects` | none | DePIN project data |\n| `l1data` | none | L1 blockchain statistics |\n| `nuclear` | `start`, `end` | Nuclear outage data |\n\n---\n\n## What's next?\n\nQuicksilver is just getting started, and there's immense potential for growth. We're inviting contributors to join us in building the future of AI agents and DePIN integration. Here are some areas where you can make a difference:\n\n- **Integrate DePIN network**: Be part of Quicksilver’s core vision by researching and integrating a Decentralized Physical Infrastructure Network (DePIN). This is an opportunity to demonstrate how DePINs can act as the “sensorial” layer for AI agents.\n- **Implement advanced memory types**: Help Quicksilver remember more effectively! Experiment with innovative memory systems like conversation buffers or vector databases to enhance context retention and agent intelligence.\n- **Develop custom tools**: Bring your creativity to life by building tools for new functionalities, such as calendar access, task management, or data analysis. Your contributions can significantly expand the agent’s utility.\n- **Enhance workflow logic**: Improve the agent’s decision-making capabilities to make better use of the tools and resources available. Collaborate to create smarter, more adaptable workflows.\n\nHave an idea outside of this list? We'd love to hear it!\n\n## Quicksilver works with Eliza\n\nQuicksilver is serving the sentient AI queries as the DePIN-Plugin on [Eliza](https://github.com/elizaOS/eliza). You can simply enable the plugin and start using it. With Quicksilver, your Eliza agent will gain sentient-like capabilities to interact intelligently with the world. The current capabilities are listed above. If you like to add more capabilities, please refer to the [Contributing](#contributing) section.\n\n## LLM Provider Configuration\n\nQuicksilver supports multiple LLM providers and uses a dual-LLM architecture with a fast LLM for initial processing and a primary LLM for complex reasoning. Configure your providers in the `.env` file:\n\n```env\n# LLM Provider API Keys\nOPENAI_API_KEY=your_openai_api_key\nANTHROPIC_API_KEY=your_anthropic_api_key\nDEEPSEEK_API_KEY=your_deepseek_api_key\n\n# LLM Model Selection\nFAST_LLM_MODEL=gpt-4o-mini    # Model for fast processing\nLLM_MODEL=deepseek-chat       # Model for primary reasoning\n```\n\n### Supported Providers\n\n- **OpenAI**: Use OpenAI's models by setting the provider to `openai`\n  - Default model: `gpt-4o-mini`\n- **Anthropic**: Use Claude models by setting the provider to `anthropic`\n  - Default model: `claude-3-5-haiku-latest`\n- **DeepSeek**: Use DeepSeek's models by setting the provider to `deepseek`\n  - Default model: `deepseek-chat`\n  - Note: DeepSeek uses OpenAI-compatible API endpoints\n\nYou can configure both the fast LLM and primary LLM providers in the SentientAI initialization:\n\n```typescript\nnew SentientAI({\n  fastLLMProvider: 'openai', // For quick processing\n  llmProvider: 'deepseek', // For main reasoning\n});\n```\n\n## Managing Multiple Instances\n\nQuicksilver supports running multiple instances with different tool configurations. This is useful when you want to:\n\n- Run specialized instances for different use cases\n- Isolate tool sets for different environments\n- Manage resource usage by enabling only necessary tools\n- Test different tool combinations\n\n### Configuration Structure\n\n```bash\nconfigs/\n└── instances/           # Your instance-specific configurations (gitignored)\n    ├── weather.env      # Instance with only weather-related tools\n    ├── news.env         # Instance with news and analytics tools\n    └── full.env         # Instance with all tools enabled\n```\n\n### Creating a New Instance\n\n1. Copy the template configuration:\n\n   ```bash\n   cp .env.template configs/instances/myinstance.env\n   ```\n\n2. Edit the configuration file:\n\n   ```env\n   # configs/instances/myinstance.env\n\n   # Enable only required tools\n   ENABLED_TOOLS=weather-current,weather-forecast,news\n\n   # Configure instance-specific API keys\n   NUBILA_API_KEY=your_key\n   NEWSAPI_API_KEY=your_key\n\n   # Other configuration...\n   PORT=8001\n   ```\n\n### Running Instances\n\nUsing Docker Compose:\n\n```bash\n# Start a specific instance\nCONFIG_PATH=configs/instances/weather.env docker compose up instance1\n\n# Run multiple instances\nCONFIG_PATH=configs/instances/weather.env docker compose up instance1 \u0026 \\\nCONFIG_PATH=configs/instances/news.env docker compose up instance2\n```\n\nUsing environment files directly:\n\n```bash\n# Start with specific config\nbun run start --env-file configs/instances/weather.env\n\n# Or using environment variable\nCONFIG_PATH=configs/instances/weather.env bun run start\n```\n\n### Example Configurations\n\n1. Weather-focused Instance:\n\n```env\n# configs/instances/weather.env\nENABLED_TOOLS=weather-current,weather-forecast\nNUBILA_API_KEY=your_key\nPORT=8001\n```\n\n2. News and Analytics Instance:\n\n```env\n# configs/instances/news.env\nENABLED_TOOLS=news,depin-metrics,depin-projects\nNEWSAPI_API_KEY=your_key\nDEPIN_API_KEY=your_key\nPORT=8002\n```\n\n3. IoT Data Instance:\n\n```env\n# configs/instances/iot.env\nENABLED_TOOLS=dimo,l1data\nCLIENT_ID=your_client_id\nREDIRECT_URI=your_uri\nAPI_KEY=your_key\nPORT=8003\n```\n\n### Docker Compose Example\n\n```yaml\nversion: '3'\n\nservices:\n  # Weather instance\n  weather:\n    image: qs:main\n    env_file: ${CONFIG_PATH:-configs/instances/weather.env}\n    ports:\n      - '8001:8000'\n    restart: always\n\n  # News instance\n  news:\n    image: qs:main\n    env_file: ${CONFIG_PATH:-configs/instances/news.env}\n    ports:\n      - '8002:8000'\n    restart: always\n\n  # IoT instance\n  iot:\n    image: qs:main\n    env_file: ${CONFIG_PATH:-configs/instances/iot.env}\n    ports:\n      - '8003:8000'\n    restart: always\n```\n\n### Available Tools\n\nThe following tools can be enabled in your configuration:\n\n| Tool Name          | Description           | Required Environment Variables         |\n| ------------------ | --------------------- | -------------------------------------- |\n| `news`             | News API integration  | `NEWSAPI_API_KEY`                      |\n| `weather-current`  | Current weather data  | `NUBILA_API_KEY`                       |\n| `weather-forecast` | Weather forecasts     | `NUBILA_API_KEY`                       |\n| `depin-metrics`    | DePIN network metrics | `DEPIN_API_KEY`                        |\n| `depin-projects`   | DePIN project data    | `DEPIN_API_KEY`                        |\n| `l1data`           | L1 blockchain data    | -                                      |\n| `dimo`             | Vehicle IoT data      | `CLIENT_ID`, `REDIRECT_URI`, `API_KEY` |\n| `nuclear`          | Nuclear outage data   | `EIA_API_KEY`                          |\n\n### Best Practices\n\n1. **Configuration Management**:\n\n   - Keep sensitive data out of version control\n   - Use descriptive names for config files\n   - Document required environment variables\n\n2. **Resource Optimization**:\n\n   - Enable only necessary tools per instance\n   - Monitor resource usage\n   - Use appropriate container resources\n\n3. **Deployment**:\n\n   - Use different ports for different instances\n   - Set up health checks\n   - Implement proper logging\n\n4. **Security**:\n   - Don't commit API keys\n   - Use separate API keys per instance\n   - Implement rate limiting\n\n## Contributing\n\nWe welcome contributions! To contribute:\n\n1. Fork the repository.\n2. Create a new branch:\n   ```bash\n   git checkout -b feature-name\n   ```\n3. Make your changes and test thoroughly.\n4. Submit a pull request with a detailed description.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiotexproject%2Fquicksilver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiotexproject%2Fquicksilver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiotexproject%2Fquicksilver/lists"}