{"id":26033130,"url":"https://github.com/uraniumcorporation/maiar-ai","last_synced_at":"2025-04-13T07:50:16.472Z","repository":{"id":276232992,"uuid":"925378005","full_name":"UraniumCorporation/maiar-ai","owner":"UraniumCorporation","description":"Maiar: A Composable, Plugin-Based AI Agent Framework","archived":false,"fork":false,"pushed_at":"2025-03-31T08:41:57.000Z","size":2394,"stargazers_count":65,"open_issues_count":7,"forks_count":27,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-04T15:11:57.254Z","etag":null,"topics":["agent","ai","framework","plugin"],"latest_commit_sha":null,"homepage":"https://maiar.dev","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/UraniumCorporation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-31T19:04:45.000Z","updated_at":"2025-03-31T08:50:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"c930ae35-3a0c-4e78-bf3d-c2f7c44b36b5","html_url":"https://github.com/UraniumCorporation/maiar-ai","commit_stats":null,"previous_names":["uraniumcorporation/maiar-ai"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UraniumCorporation%2Fmaiar-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UraniumCorporation%2Fmaiar-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UraniumCorporation%2Fmaiar-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UraniumCorporation%2Fmaiar-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UraniumCorporation","download_url":"https://codeload.github.com/UraniumCorporation/maiar-ai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681494,"owners_count":21144700,"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","framework","plugin"],"created_at":"2025-03-06T23:09:42.630Z","updated_at":"2025-04-13T07:50:16.461Z","avatar_url":"https://github.com/UraniumCorporation.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Maiar banner](./website/static/img/maiar-banner.png)\n\n# MAIAR: A Composable, Plugin-Based AI Agent Framework\n\nMAIAR is designed around the **thesis** that AI agents, in their current iteration, primarily consist of three major steps:\n\n1. **Data Ingestion \u0026 Triggers** – What causes the AI to act.\n2. **Decision-Making** – How the AI determines the appropriate action.\n3. **Action Execution** – Carrying out the selected operation.\n\nInstead of rigid workflows or monolithic agent logic, Maiar abstracts these steps into a **modular, plugin-based system**. Developers define **triggers** and **actions** as standalone plugins, while the core runtime dynamically handles decision-making. This enables a highly extensible, composable, and model driven framework where new functionality can be added seamlessly.\n\n## Table of Contents\n\n- [Getting Started Running MAIAR](#getting-started-running-maiar)\n- [Getting Started Contributing to MAIAR](#getting-started-contributing-to-maiar)\n- [How It Works](#how-it-works)\n- [Pipes \u0026 Context Chains](#pipes-context-chains)\n- [Extensibility \u0026 Modularity](#extensibility-modularity)\n- [Design Principles](#design-principles)\n\n## Getting Started Running MAIAR\n\nWelcome to MAIAR! This guide will help you set up and run your own AI agent using the MAIAR framework.\n\n### Prerequisites\n\nBefore you begin, make sure you have the following installed:\n\n- [Node.js](https://nodejs.org/) (v22.13.1) - We recommend using [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) to manage Node.js versions:\n\n```bash\nnvm install 22.13.1\nnvm use 22.13.1\n```\n\n- A package manager ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/), or [pnpm](https://pnpm.io/))\n\n### Quick Start\n\n1. Create a new directory for your project and initialize it:\n\n```bash\nmkdir my-maiar-agent\ncd my-maiar-agent\n```\n\n```bash\npnpm init\n```\n\n2. Install the core MAIAR packages, providers, and some starter plugins:\n\n```bash\npnpm add @maiar-ai/core @maiar-ai/model-openai @maiar-ai/memory-sqlite @maiar-ai/plugin-terminal @maiar-ai/plugin-text dotenv\n```\n\n3. Create a new directory called `src` in your project root and create a new file called `index.ts` in it:\n\n```typescript\nimport \"dotenv/config\";\n\nimport path from \"path\";\n\nimport { createRuntime } from \"@maiar-ai/core\";\n\nimport { OpenAIProvider } from \"@maiar-ai/model-openai\";\n\nimport { SQLiteProvider } from \"@maiar-ai/memory-sqlite\";\n\nimport { PluginTerminal } from \"@maiar-ai/plugin-terminal\";\nimport { PluginTextGeneration } from \"@maiar-ai/plugin-text\";\n\nconst runtime = createRuntime({\n  models: [\n    new OpenAIProvider({\n      apiKey: process.env.OPENAI_API_KEY as string,\n      model: \"gpt-3.5-turbo\"\n    })\n  ],\n  memory: new SQLiteProvider({\n    dbPath: path.join(process.cwd(), \"data\", \"conversations.db\")\n  }),\n  plugins: [\n    new PluginTextGeneration(),\n    new PluginTerminal({ user: \"test\", agentName: \"maiar-starter\" })\n  ],\n  capabilityAliases: []\n});\n\n// Start the runtime\nconsole.log(\"Starting agent...\");\nruntime.start().catch((error) =\u003e {\n  console.error(\"Failed to start agent:\", error);\n  process.exit(1);\n});\n\n// Handle shutdown gracefully\nprocess.on(\"SIGINT\", async () =\u003e {\n  console.log(\"Shutting down agent...\");\n  await runtime.stop();\n  process.exit(0);\n});\n```\n\n4. Create a `.env` file in your project root. For our example, we'll use the OpenAI API key:\n\n\u003e [!INFO]\n\u003e Since we're using OpenAI's API for this quickstart, you'll need to:\n\u003e\n\u003e 1. Create an OpenAI account at [platform.openai.com](https://platform.openai.com)\n\u003e 2. Generate an API key in your account settings\n\u003e 3. Add funds to your account to use the API\n\u003e 4. Create a `.env` file with your API key as shown below\n\n```bash\nOPENAI_API_KEY=your_api_key_here\n```\n\n5. Add TypeScript configuration. Create a `tsconfig.json`:\n\n```json\n{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"CommonJS\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"outDir\": \"./dist\"\n  },\n  \"include\": [\"src/**/*.ts\"],\n  \"exclude\": [\"node_modules\"]\n}\n```\n\n6. Add build and start scripts to your `package.json` under the `scripts` section:\n\n```json\n  \"build\": \"tsc\",\n  \"start\": \"node dist/index.js\"\n```\n\n7. Build and start your agent:\n\n```bash\npnpm build\npnpm start\n```\n\n8. Test your agent by starting `maiar-chat`:\n\n```bash\npnpm maiar-chat\n```\n\nYou should see a terminal prompt to chat with your agent.\n\n## Getting Started Contributing to Maiar\n\n### Prerequisites\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e **Please make sure to checkout the [contributing guide](.github/CONTRIBUTING.md) first and foremost**\n\n1. Make sure you have the following installed:\n\n- [Node.js](https://nodejs.org/) (v22.13.1) - We recommend using [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) to manage Node.js versions:\n\n```bash\nnvm install 22.13.1\nnvm use 22.13.1\n```\n\n- The [pnpm](https://pnpm.io/) package manager explicitly - Required for managing the monorepo workspace and its dependencies efficiently\n\n2. Install the project dependencies:\n\n```bash\n# From the root of the repository\npnpm install\n```\n\n3. Start the development environment. You'll need two terminal windows:\n\n**Terminal 1 - Core Packages:**\n\n```bash\n# From the root of the repository\npnpm dev\n```\n\nThis command watches for changes in the core packages (`packages/**/*.ts`) and automatically rebuilds them. It:\n\n1. Cleans any previous build state\n2. Builds all core packages\n3. Updates the `.build-complete` marker file with current timestamp to indicate the core packages build is finished as a state file to communicate with the development project\n4. Watches for changes and repeats the process\n\n**Terminal 2 - Development Project:**\n\n```bash\n# From the root of the repository\ncd maiar-starter # or your own development project\npnpm dev\n```\n\nThis command runs the starter project in development mode. It:\n\n1. Watches for changes in both the starter project's source files and the core packages through the `.build-complete` marker file\n2. Rebuilds the starter project\n3. Restarts the application automatically and handles exiting gracefully so orphaned processes are cleaned up\n\nThis setup ensures that changes to either the core packages or the starter project are automatically rebuilt and reflected in your running application, providing a seamless development experience.\n\n\u003e [!NOTE]\n\u003e\n\u003e The `maiar-starter` project serves as a reference implementation demonstrating how to develop against the core MAIAR packages. You can apply this same development setup to any project that depends on MAIAR packages - simply mirror the dev script configuration and `.build-complete` marker file handling shown in the starter project's package.json. The key focus of this repository is the core packages in `packages/*`, with `maiar-starter` serving as an example consumer.\n\n## **How It Works**\n\nAt its core, MAIAR builds execution pipelines dynamically. When an event or request is received, the runtime:\n\n1. **Processes triggers** to determine when and how the AI should act.\n2. **Uses model assisted reasoning** to construct an execution pipeline.\n3. **Runs plugins in sequence**, modifying a structured **context chain** as it progresses.\n\nRather than hardcoding client logic, MAIAR produces **emergent behavior** by selecting the most relevant plugins and actions based on context. This enables adaptability and ensures that agents can evolve without rewriting core logic.\n\n## **Pipes \u0026 Context Chains**\n\nMAIAR's architecture is influenced by **Unix pipes**, where structured input flows through a sequence of operations, using a standard in and out data interface. Each plugin acts as an independent unit:\n\n1. **Receives input (context) from prior steps**\n2. **Performs a specific operation**\n3. **Outputs a structured result to the next step**\n\nThis structured **context chain** ensures:\n\n- **Highly composable plugins** – New functionality can be added without modifying existing logic.\n- **Dynamic execution pipelines** – Workflows are built on-the-fly rather than being hardcoded.\n- **Transparent debugging \u0026 monitoring** – Each step in the chain is tracked and can be audited.\n\nThis design enables MAIAR to remain **declarative** and **extensible**, allowing developers to build complex AI workflows without locking themselves into rigid architectures.\n\n## **Extensibility \u0026 Modularity**\n\nMAIAR is intentionally **unopinionated** about external dependencies, ensuring developers have full control over their infrastructure. The framework avoids enforcing specific technologies, making it easy to integrate with:\n\n- **Database Adapters** – Works with any database system.\n- **Model Providers** – Supports OpenAI, local models, or custom integrations.\n- **Logging \u0026 Monitoring** – Custom logging systems can be plugged in without modifying core logic.\n- **Future Expansions** – As needs evolve, new capabilities can be added without disrupting existing workflows.\n\nBy maintaining a **flexible core**, MAIAR ensures that AI agents can adapt to different environments and use cases without unnecessary constraints.\n\n## **Design Principles**\n\n- **Plugin-First** – Every capability, from event ingestion to action execution, is encapsulated in a plugin.\n- **Modular \u0026 Composable** – No rigid loops, no hardcoded workflows. The agent dynamically assembles execution pipelines.\n- **Model Driven Behavior** – Instead of pre-defined workflows, the AI evaluates its available tools and selects the best course of action.\n- **Declarative Plugin Interface** – Plugins declare their triggers and actions, while the runtime orchestrates them.\n- **Pipes \u0026 Context Chains** – Input flows through plugins in a structured sequence, mirroring Unix pipes.\n- **Extensibility \u0026 Flexibility** – The core library avoids enforcing specific tools or integrations. It's designed around interfaces and providers that allow you to plug in your own tools and integrations.\n\n## **Why MAIAR?**\n\n- **Effortless Development** – Define a plugin, specify its triggers \u0026 actions, and the agent handles the rest.\n- **Dynamic AI Workflows** – Pipelines are built on-the-fly, allowing flexible and emergent behavior.\n- **Composability-First** – Standardized context chains make plugins reusable and easily integrable.\n- **Unopinionated \u0026 Extensible** – Developers have full control over databases, models, and infrastructure choices.\n\nMAIAR isn't just another AI agent framework—it's a **declarative, extensible, and composable way to build intelligent applications**. Whether you're adding new capabilities or integrating with existing platforms, MAIAR makes it simple.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furaniumcorporation%2Fmaiar-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furaniumcorporation%2Fmaiar-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furaniumcorporation%2Fmaiar-ai/lists"}