# airweave - Doramagic AI Context Pack

> Positioning: a pre-install experience and judgment asset. It helps the host AI get off to a good start, but it does not mean the project has already been installed, run, or validated.

## Sufficiency Principle

- **Sufficiency over compression**: The AI Context Pack should be sufficient for the host AI to understand the project's value, capability boundaries, entrypoints, risks, and evidence sources before starting work; it may be layered, but it does not aim for the shortest possible summary.
- **Compression policy**: Compress only noise and duplication, never context that affects judgment or the quality of the work.

## How the Host AI Should Use This

You are reading the AI Context Pack that Doramagic compiled for airweave. Treat it as pre-work context: help the user understand who it fits, what it can do, how to start, what must be verified after install, and where the risks are. Do not claim that you have already installed, run, or executed the target project.

## Claim Consumption Rules

- **Fact source**: Repo Evidence + Claim/Evidence Graph; the Human Wiki only supplies salience, terminology, and narrative structure.
- **Minimum status for a fact**: `supported`
- `supported`: May be used as a project fact, but the answer must cite the claim_id and evidence path.
- `weak`: Usable only as a low-confidence lead; the user must be asked to keep verifying.
- `inferred`: Usable only for risk notes or open questions; must not be packaged as a project fact.
- `unverified`: Must not be used as fact; state clearly that evidence is insufficient.
- `contradicted`: Must show the conflicting sources and must not force a single version on the user's behalf.

## Who It Fits Best

- **Developers already using host AIs such as Claude/Codex/Cursor/Gemini**: The README or plugin config mentions multiple host AIs. Evidence: `README.md` Claim: `clm_0002` supported 0.86

## What It Can Do

- **Command-Line Startup or Install Flow** (Verify after install): The project documentation contains runnable commands; real use requires running them in a local or host environment. Evidence: `CLAUDE.md`, `README.md` Claim: `clm_0001` supported 0.86

## How to Start

- `git clone https://github.com/airweave-ai/airweave.git` Evidence: `README.md` Claim: `clm_0003` supported 0.86
- `pip install airweave-sdk        # Python` Evidence: `README.md` Claim: `clm_0004` supported 0.86
- `npm install @airweave/sdk       # TypeScript` Evidence: `README.md` Claim: `clm_0005` supported 0.86
- `pip install airweave-cli` Evidence: `README.md` Claim: `clm_0006` supported 0.86
- `npm install                    # Install dependencies` Evidence: `CLAUDE.md` Claim: `clm_0007` supported 0.86

## Continue-or-Stop Decision Card

- **Current recommendation**: Needs admin / security approval
- **Why**: Continuing may involve secrets, accounts, external services, or sensitive context; get admin or security approval first.

### 30-Second Read

- **What to do now**: Needs admin / security approval
- **Minimum safe next step**: Run Prompt Preview first; if credentials or an enterprise environment are involved, get approval before trialing
- **Do not trust yet**: Tool permission boundaries cannot be trusted before install.
- **Continuing will touch**: Command execution, Host AI configuration, Local environment or project files

### What You Can Trust Now

- **Target-audience signal: Developers already using host AIs such as Claude/Codex/Cursor/Gemini** (supported): Backed by a supported claim or project evidence, but that still is not the same as real install results. Evidence: `README.md` Claim: `clm_0002` supported 0.86
- **Capability exists: Command-Line Startup or Install Flow** (supported): You can trust that the project contains signals of this capability; whether it fits your specific task still needs trial or after-install verification. Evidence: `CLAUDE.md`, `README.md` Claim: `clm_0001` supported 0.86
- **There are Quick Start / install-command signals** (supported): You can trust that the docs mention a startup or install entrypoint; do not run it directly in your primary environment because of that. Evidence: `README.md` Claim: `clm_0003` supported 0.86

### What You Cannot Trust Yet

- **Tool permission boundaries cannot be trusted before install.** (unverified): MCP/tool projects usually touch files, the network, the browser, or external APIs, so permissions and logs must be checked for real.
- **Real output quality cannot be trusted before install.** (unverified): Prompt Preview can only show how it guides you; it cannot prove result quality in the real project.
- **Host AI version compatibility cannot be trusted before install.** (unverified): Host loading rules and version differences across Claude, Cursor, Codex, Gemini, and others must be verified in a real environment.
- **That it will not pollute your existing host AI's behavior cannot be trusted directly.** (inferred): Skill, plugin, and AGENTS/CLAUDE/GEMINI instructions may change the host AI's default behavior. Evidence: `CLAUDE.md`
- **Safe rollback cannot be assumed by default.** (unverified): Unless the project clearly provides uninstall and recovery instructions, verify in an isolated environment first.
- **After a real install, is it compatible with the user's current host AI version?** (unverified): Compatibility can only be verified in the actual host environment.
- **Does the project's output quality meet the user's specific task?** (unverified): The pre-install preview can only show flow and boundaries; it cannot replace real evaluation.
- **Do the install commands require network access, permissions, or global writes?** (unverified): This affects install risk in both enterprise and personal environments. Evidence: `README.md`

### What Continuing Will Touch

- **Command execution**: Package managers, network downloads, the local plugin directory, project config, or the user's home directory. Why: Running the very first command can already change your environment; decide whether it is worth running first. Evidence: `CLAUDE.md`, `README.md`
- **Host AI configuration**: The plugin, Skill, or rule-loading config of hosts like Claude/Codex/Cursor/Gemini/OpenCode. Why: Host configuration changes how the AI works afterward and may conflict with the user's existing rules. Evidence: `CLAUDE.md`
- **Local environment or project files**: Install results, plugin caches, project config, or local dependency directories. Why: The write scope and rollback path cannot be proven before install and need isolated verification. Evidence: `CLAUDE.md`, `README.md`
- **Environment variables / API keys**: Project entry docs explicitly showing API key, token, secret, or account credential configuration. Why: If a real install needs credentials, use test credentials first and go through a permission/compliance review. Evidence: `examples/README.md`, `examples/quickstart_tutorial.py`, `mcp/README.md`, `mcp/config-example.json` et al.
- **Host AI context**: The AI Context Pack, Prompt Preview, Skill routing, risk rules, and project facts. Why: Importing context affects the host AI's later judgment, so avoid packaging unverified items as facts.

### Minimum Safe Next Steps

- **Run Prompt Preview first**: Use a pre-install interactive trial to judge whether the way of working fits; it needs no authorization or environment change. (applies when: Applies to any project, especially when output quality is unknown.)
- **Trial-install only in an isolated directory or a test account**: Avoid letting install commands pollute your primary host AI, real projects, or home directory. (applies when: When there are signals of command execution, plugin config, or local writes.)
- **Back up your host AI configuration first**: Skill, plugin, and rule files may change the default behavior of Claude/Cursor/Codex. (applies when: When there is a plugin manifest, a Skill, or a host rule entrypoint.)
- **Do not use real production credentials**: Once an environment variable / API key enters the host or toolchain, it can create account and compliance risk. (applies when: When environment signals like API, TOKEN, KEY, or SECRET appear.)
- **After install, verify just one minimal task**: Verify loading, compatibility, output quality, and rollback first, then decide whether to use it deeply. (applies when: When moving from a trial into a real workflow.)

### Exit Plan

- **Preserve the pre-install state**: Record the original host config and project state so you can later judge whether it is recoverable.
- **Be ready to remove the host plugin / Skill / rule entrypoint**: If behavior is off after the trial install, you can restore the host AI to its pre-trial state.
- **Record the install commands and written paths**: Without clear uninstall instructions, you at least need to know which directories or configs to clean up manually.
- **Be ready to revoke test API keys or tokens**: If test credentials leak or are misused, you can cut losses quickly.
- **If there is no rollback path, do not enter your primary environment**: No rollback is a blocker before continuing; do not proceed on trust or luck.

## What Can Only Be Previewed

- Explain who the project fits and what it can do
- Demonstrate a typical conversation flow based on project docs
- Help the user decide whether it is worth installing or researching further

## What Must Be Verified After Install

- Actually installing the Skill, plugin, or CLI
- Running scripts, modifying local files, or accessing external services
- Verifying real output quality, performance, and compatibility

## Boundary & Risk Decision Card

- **Mistaking the pre-install preview for a real run**: The user may overestimate how much configuration, permission, and compatibility verification the project has already done. Mitigation: Clearly separate prompt_preview_can_do from runtime_required. Claim: `clm_0008` inferred 0.45
- **Command execution will modify the local environment**: Install commands may write to the user's home directory, the host plugin directory, or project configuration. Mitigation: Run in an isolated environment or a test account first. Evidence: `CLAUDE.md`, `README.md` Claim: `clm_0009` supported 0.86
- **To confirm**: After a real install, is it compatible with the user's current host AI version?. Why: Compatibility can only be verified in the actual host environment.
- **To confirm**: Does the project's output quality meet the user's specific task?. Why: The pre-install preview can only show flow and boundaries; it cannot replace real evaluation.
- **To confirm**: Do the install commands require network access, permissions, or global writes?. Why: This affects install risk in both enterprise and personal environments.

## Pre-Work Working Context

### Loading Order

- First read how_to_use.host_ai_instruction to establish the boundaries of this pre-install judgment asset.
- Read claim_graph_summary to confirm facts come from the Claim/Evidence Graph, not the Human Wiki narrative.
- Then read intended_users, capabilities, and quick_start_candidates to judge whether the user is a match.
- When you need to carry out a concrete task, check role_skill_index first, then evidence_index.
- For real install, file modification, network access, performance, or compatibility questions, turn to risk_card and boundaries.runtime_required.

### Task Routes

- **Command-Line Startup or Install Flow**: State that this is an after-install capability first, then give a pre-install checklist. Boundary: Must be verified after a real install or run. Evidence: `CLAUDE.md`, `README.md` Claim: `clm_0001` supported 0.86

### Context Scale

- Total files: 1870
- Important-file coverage: 40/1870
- Evidence index entries: 80
- Role / Skill entries: 16

### Handling Insufficient Evidence

- **missing_evidence**: State that evidence is insufficient and ask the user for the target file, a README section, or after-install verification records; do not fill in facts.
- **out_of_scope_request**: State that the task is beyond the current AI Context Pack's evidence scope and suggest the user check the Human Manual or verify after a real install.
- **runtime_request**: Provide a pre-install checklist and command sources, but do not run commands for the user or claim they have been run.
- **source_conflict**: Show the conflicting sources side by side, mark them as unverified, and do not force a single version.

## Prompt Recipes

### Fit assessment

- Goal: Judge whether this project fits the user's current task.
- Expected output: A fit conclusion, key reasons, evidence citations, what can be previewed before install, what must be verified after install, and a next-step recommendation.

```text
Based on the AI Context Pack for airweave, ask me 3 necessary questions first, then judge whether it fits my task. The answer must cover: who it fits, what it can do, what it cannot do, whether it is worth installing, and where the evidence comes from. Every project fact must cite evidence_refs, source_paths, or a claim_id.
```

### Pre-install experience

- Goal: Let the user feel the core workflow before installing, while avoiding packaging the preview as real capability or a marketing promise.
- Expected output: An experience script with boundary labels, an after-install verification checklist, and a cautious recommendation; with no real-run promises or strong marketing language.

```text
Treat airweave as a pre-install experience asset, not an already-installed tool or a real runtime environment.

Output exactly four parts:
1. Ask me 3 necessary questions first.
2. Give an "experience script": use the three labels [Previewable before install], [Must verify after install], and [Insufficient evidence] to show how it might guide the workflow.
3. Give an after-install verification checklist: list which capabilities can only be confirmed after a real install, real host loading, and a real project run.
4. Give a cautious recommendation: only "worth researching/trialing further", "add information before deciding", or "not recommended to continue"; do not endorse the project.

Hard boundaries:
- Do not claim you have installed, run, executed tests, modified files, or produced real results.
- Do not write promise-like phrasing such as "auto-adapts", "guarantees passing", "perfect fit", or "strongly recommend installing".
- If you describe how it works after install, you must use a conditional such as "if installed successfully and the host loads the Skill correctly, it might...".
- The experience script may only be written as "example lines / hypothetical flow": use "might ask / might suggest / might show", not "has written, has generated, has passed, is running, is generating".
- Prompt Preview does not hand out install commands; if the user is ready to trial, only prompt them to read Quick Start and the Risk Card first and to verify in an isolated environment.
- Every project fact must come from a supported claim, evidence_refs, or source_paths; inferred/unverified items can only be risks or open questions.

```

### Role / Skill selection

- Goal: Pick the best-matching asset from the project's roles or Skills.
- Expected output: A list of candidate roles or Skills, each with an applicable scenario, evidence paths, risk boundary, and whether after-install verification is needed.

```text
Read role_skill_index and recommend 3-5 of the most relevant roles or Skills for my target task. For each recommendation, state the applicable scenario, likely output, risk boundary, and evidence_refs.
```

### Risk pre-check

- Goal: Identify environment, permission, rule-conflict, and quality risks before installing or adopting.
- Expected output: A checklist of environment, permission, dependency, license, host-conflict, quality risk, and unknown items.

```text
Based on risk_card, boundaries, and quick_start_candidates, give me a pre-install risk pre-check list. Do not run commands for me; only explain what I should check, why, and what impact a failure would have.
```

### Host AI kickoff instruction

- Goal: Turn the project context into a host AI instruction for the start of a conversation.
- Expected output: A pre-work instruction with clear boundaries and clear evidence citations, suitable to copy to a host AI.

```text
Based on the AI Context Pack for airweave, generate a pre-work instruction I can paste to my host AI. This instruction must obey not_runtime=true and must not claim the project has been installed, run, or produced real results.
```

## Role / Skill Index

- Indexed 16 role / Skill / project-doc entries.

- **What is Airweave?** (project_doc): Open-source context retrieval layer for AI agents and RAG systems. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `README.md`
- **Airweave Connect** (project_doc): Airweave Connect is a hosted UI component that enables end-users to connect data sources to the Airweave platform. It provides a Plaid-style Connect modal experience, designed to be embedded as an iframe in parent applications. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `connect/README.md`
- **Developer Enablement Materials** (project_doc): This folder contains educational materials and tutorials to help developers get started with Airweave quickly and effectively. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `examples/README.md`
- **Fern Module** (project_doc): This directory contains the Fern API definition and configuration for Airweave's API documentation and SDK generation. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `fern/README.md`
- **Airweave Frontend** (project_doc): The Airweave frontend is a React/TypeScript application that provides the UI for the Airweave platform. Airweave is an open-source platform that makes any app searchable for your agent by syncing data from various sources into vector and graph databases with minimal configuration. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `frontend/README.md`
- **Airweave MCP Search Server** (project_doc): ! npm version https://img.shields.io/npm/v/airweave-mcp-search.svg https://www.npmjs.com/package/airweave-mcp-search ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Node.js = 20 https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg https://nodejs.org/ ! MCP Protocol https://img.shields.io/badge/MCP-2025--03--26-blue.svg https://modelcontextprotocol.io/ Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `mcp/README.md`
- **Monke 🐒🥁 - Airweave Integration Testing Framework** (project_doc): Monke 🐒🥁 - Airweave Integration Testing Framework Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `monke/README.md`
- **Airweave Analytics Module** (project_doc): This module provides PostHog analytics integration for Airweave, enabling comprehensive tracking of user behavior, business metrics, and system performance. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `backend/airweave/analytics/README.md`
- **Temporal Integration** (project_doc): This directory contains the Temporal workflow integration for Airweave. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `backend/airweave/domains/temporal/README.md`
- **@airweave/connect-react** (project_doc): React hook for integrating Airweave Connect into your application. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `connect/packages/react/README.md`
- **Airweave Webhook Demo** (project_doc): A minimal FastAPI app that receives Airweave webhook events and streams them to a browser UI in real time via WebSocket. Useful for testing and debugging your webhook integration locally. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `examples/webhook-demo/README.md`
- **Airweave API SDK and Documentation Generation** (project_doc): Airweave API SDK and Documentation Generation Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `fern/scripts/README.md`
- **Monke Frontend** (project_doc): Vite + React + Tailwind UI for Monke runs. Proxies API/WS to localhost:8081. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `monke/frontend/README.md`
- **CLAUDE.md** (project_doc): This file provides guidance to Claude Code claude.ai/code when working with code in this repository. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `CLAUDE.md`
- **Contributing to Airweave** (project_doc): Thank you for your interest in contributing to Airweave! This document provides guidelines and instructions for contributing to the project. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `CONTRIBUTING.md`
- **Airweave Backend Architecture Refactor v0** (project_doc): Airweave Backend Architecture Refactor v0 Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `backend/airweave/architecture-refactor.md`

## Evidence Index

- Indexed 80 evidence entries.

- **What is Airweave?** (documentation): Open-source context retrieval layer for AI agents and RAG systems. Evidence: `README.md`
- **Airweave Connect** (documentation): Airweave Connect is a hosted UI component that enables end-users to connect data sources to the Airweave platform. It provides a Plaid-style Connect modal experience, designed to be embedded as an iframe in parent applications. Evidence: `connect/README.md`
- **Developer Enablement Materials** (documentation): This folder contains educational materials and tutorials to help developers get started with Airweave quickly and effectively. Evidence: `examples/README.md`
- **Fern Module** (documentation): This directory contains the Fern API definition and configuration for Airweave's API documentation and SDK generation. Evidence: `fern/README.md`
- **Airweave Frontend** (documentation): The Airweave frontend is a React/TypeScript application that provides the UI for the Airweave platform. Airweave is an open-source platform that makes any app searchable for your agent by syncing data from various sources into vector and graph databases with minimal configuration. Evidence: `frontend/README.md`
- **Airweave MCP Search Server** (documentation): ! npm version https://img.shields.io/npm/v/airweave-mcp-search.svg https://www.npmjs.com/package/airweave-mcp-search ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Node.js = 20 https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg https://nodejs.org/ ! MCP Protocol https://img.shields.io/badge/MCP-2025--03--26-blue.svg https://modelcontextprotocol.io/ Evidence: `mcp/README.md`
- **Monke 🐒🥁 - Airweave Integration Testing Framework** (documentation): Monke 🐒🥁 - Airweave Integration Testing Framework Evidence: `monke/README.md`
- **Airweave Analytics Module** (documentation): This module provides PostHog analytics integration for Airweave, enabling comprehensive tracking of user behavior, business metrics, and system performance. Evidence: `backend/airweave/analytics/README.md`
- **Temporal Integration** (documentation): This directory contains the Temporal workflow integration for Airweave. Evidence: `backend/airweave/domains/temporal/README.md`
- **@airweave/connect-react** (documentation): React hook for integrating Airweave Connect into your application. Evidence: `connect/packages/react/README.md`
- **Airweave Webhook Demo** (documentation): A minimal FastAPI app that receives Airweave webhook events and streams them to a browser UI in real time via WebSocket. Useful for testing and debugging your webhook integration locally. Evidence: `examples/webhook-demo/README.md`
- **Airweave API SDK and Documentation Generation** (documentation): Airweave API SDK and Documentation Generation Evidence: `fern/scripts/README.md`
- **Monke Frontend** (documentation): Vite + React + Tailwind UI for Monke runs. Proxies API/WS to localhost:8081. Evidence: `monke/frontend/README.md`
- **CLAUDE.md** (documentation): This file provides guidance to Claude Code claude.ai/code when working with code in this repository. Evidence: `CLAUDE.md`
- **Package** (package_manifest): { "name": "airweave-connect", "private": true, "type": "module", "exports": { ".": "./src/index.ts", "./lib/types": "./src/lib/types.ts", "./lib/connection-utils": "./src/lib/connection-utils.ts", "./lib/icons": "./src/lib/icons.ts", "./lib/theme-defaults": "./src/lib/theme-defaults.ts" }, "scripts": { "dev": "vite dev --port 8082", "build": "vite build", "start": "node .output/server/index.mjs", "preview": "vite preview", "test": "vitest run", "test:e2e": "playwright test", "lint": "eslint .", "typecheck": "tsc --noEmit" }, "dependencies": { "@base-ui/react": "^1.0.0", "@microsoft/fetch-event-source": "^2.0.1", "@number-flow/react": "^0.5.10", "@tailwindcss/vite": "^4.0.6", "@tanstack/reac… Evidence: `connect/package.json`
- **Package** (package_manifest): { "name": "vite react shadcn ts", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "vite build", "build:dev": "vite build --mode development", "lint": "eslint .", "preview": "vite preview", "test": "vitest run", "test:watch": "vitest" }, "dependencies": { "@auth0/auth0-react": "^2.2.4", "@hookform/resolvers": "^3.9.0", "@microsoft/fetch-event-source": "^2.0.1", "@radix-ui/react-alert-dialog": "^1.1.1", "@radix-ui/react-avatar": "^1.1.0", "@radix-ui/react-checkbox": "^1.1.1", "@radix-ui/react-collapsible": "^1.1.0", "@radix-ui/react-dialog": "^1.1.2", "@radix-ui/react-dropdown-menu": "^2.1.1", "@radix-ui/react-label": "^2.1.0", "@radix-ui/react-popo… Evidence: `frontend/package.json`
- **Package** (package_manifest): { "name": "airweave-mcp-search", "version": "0.5.7", "mcpName": "io.github.airweave-ai/search", "description": "MCP server for searching Airweave collections", "type": "module", "main": "build/index.js", "bin": { "airweave-mcp-search": "./build/index.js" }, "scripts": { "build": "tsc && chmod 755 build/index.js", "start": "node build/index.js", "start:http": "node build/index-http.js", "dev": "npm run build && npm run start", "dev:http": "npm run build && npm run start:http", "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage", "test:mcp": "vitest run tests/mcp-server.test.ts", "test:http": "vitest run tests/http-transport.test.ts", "test:oauth": "vitest r… Evidence: `mcp/package.json`
- **Contributing to Airweave** (documentation): Thank you for your interest in contributing to Airweave! This document provides guidelines and instructions for contributing to the project. Evidence: `CONTRIBUTING.md`
- **Package** (package_manifest): { "name": "@airweave/connect-js", "version": "0.1.0", "description": "Vanilla JavaScript SDK for Airweave Connect", "type": "module", "main": "./dist/index.cjs", "module": "./dist/index.js", "types": "./dist/index.d.ts", "unpkg": "./dist/index.iife.js", "jsdelivr": "./dist/index.iife.js", "exports": { ".": { "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }, "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" } } }, "files": "dist" , "sideEffects": false, "scripts": { "dev": "vite build --watch", "build": "tsc && vite build", "lint": "eslint .", "test": "vitest run", "test:watch": "vitest", "prepublishOnly": "npm run build" }, "peerDependencies":… Evidence: `connect/packages/js/package.json`
- **Package** (package_manifest): { "name": "@airweave/connect-react", "version": "0.1.0", "description": "React hook for Airweave Connect", "type": "module", "main": "./dist/index.cjs", "module": "./dist/index.js", "types": "./dist/index.d.ts", "exports": { ".": { "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }, "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" } } }, "files": "dist" , "sideEffects": false, "scripts": { "dev": "vite build --watch", "build": "tsc && vite build", "lint": "eslint .", "prepublishOnly": "npm run build" }, "peerDependencies": { "react": " =19.0.0", "react-dom": " =19.0.0" }, "devDependencies": { "airweave-connect": "file:../..", "@types/react": "^… Evidence: `connect/packages/react/package.json`
- **Package** (package_manifest): { "name": "monke-frontend", "version": "0.1.0", "private": true, "type": "module", "scripts": { "dev": "vite", "build": "tsc -b && vite build", "preview": "vite preview" }, "dependencies": { "react": "^18.3.1", "react-dom": "^18.3.1", "sonner": "^1.4.41" }, "devDependencies": { "@types/react": "^18.3.4", "@types/react-dom": "^18.3.0", "@vitejs/plugin-react": "^4.3.1", "autoprefixer": "^10.4.20", "postcss": "^8.4.47", "tailwindcss": "^3.4.10", "typescript": "^5.5.4", "vite": "^5.4.1" } } Evidence: `monke/frontend/package.json`
- **License** (source_file): Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: Evidence: `LICENSE`
- **Airweave Backend Architecture Refactor v0** (documentation): Airweave Backend Architecture Refactor v0 Evidence: `backend/airweave/architecture-refactor.md`
- **Docker Compose** (source_file): services: postgres: container name: airweave-db image: postgres:16 environment: POSTGRES DB: ${POSTGRES DB:-airweave} POSTGRES USER: ${POSTGRES USER} POSTGRES PASSWORD: ${POSTGRES PASSWORD} command: - "postgres" - "-c" - "max connections=200" - "-c" - "shared buffers=256MB" - "-c" - "effective cache size=1GB" ports: - "5432:5432" volumes: - postgres data:/var/lib/postgresql/data - ./init-scripts:/docker-entrypoint-initdb.d:ro healthcheck: test: "CMD-SHELL", "pg isready -U ${POSTGRES USER}" interval: 5s timeout: 5s retries: 5 redis: container name: airweave-redis image: redis:7-alpine ports: - "6379:6379" volumes: - redis data:/data healthcheck: test: "CMD", "redis-cli", "ping" interval: 5s… Evidence: `docker/docker-compose.yml`
- **1. Check for status code on SDK exceptions e.g., BadRequestError,** (source_file): T = TypeVar "T", bound=BaseModel ⋮---- class BaseLLM LLMProtocol ⋮---- MAX RETRIES = 3 INITIAL RETRY DELAY = 1.0 MAX RETRY DELAY = 30.0 RETRY MULTIPLIER = 2.0 DEFAULT TIMEOUT = 120.0 ⋮---- FATAL STATUS CODES = {400, 401, 403, 404} TRANSIENT STATUS CODES = {429, 500, 502, 503, 504} ⋮---- FATAL FALLBACK INDICATORS = TRANSIENT FALLBACK INDICATORS = ⋮---- @property def model spec self - LLMModelSpec ⋮---- @property def name self - str ⋮---- def resolve max tokens self, max tokens: int None - int ⋮---- schema json = schema.model json schema ⋮---- schema json = self. prepare schema schema json ⋮---- resolved = self. resolve max tokens max tokens ⋮---- def prepare schema self, schema json: dict st… Evidence: `backend/airweave/adapters/llm/base.py`
- **Registry** (source_file): class LLMProvider str, Enum ⋮---- CEREBRAS = "cerebras" GROQ = "groq" ANTHROPIC = "anthropic" TOGETHER = "together" MISTRAL = "mistral" ⋮---- class LLMModel str, Enum ⋮---- GPT OSS 120B = "gpt-oss-120b" ZAI GLM 4 7 = "zai-glm-4.7" ZAI GLM 5 = "zai-glm-5" CLAUDE SONNET 4 5 = "claude-sonnet-4.5" CLAUDE SONNET 4 6 = "claude-sonnet-4.6" KIMI K2 5 = "kimi-k2.5" QWEN 3 5 = "qwen-3.5" QWEN 3 5 DEDICATED = "qwen-3.5-dedicated" ZAI GLM 5 DEDICATED = "zai-glm-5-dedicated" MINIMAX M2 5 = "minimax-m2.5" MISTRAL LARGE = "mistral-large" MISTRAL SMALL = "mistral-small" MAGISTRAL SMALL = "magistral-small" ⋮---- @dataclass frozen=True class ThinkingConfig ⋮---- param name: str param value: Union str, bool,… Evidence: `backend/airweave/adapters/llm/registry.py`
- **Registry** (source_file): class TokenizerType str, Enum ⋮---- TIKTOKEN = "tiktoken" ⋮---- class TokenizerEncoding str, Enum ⋮---- O200K HARMONY = "o200k harmony" ⋮---- @dataclass frozen=True class TokenizerModelSpec ⋮---- encoding name: str ⋮---- TOKENIZER REGISTRY: dict TokenizerType, dict TokenizerEncoding, TokenizerModelSpec = { ⋮---- type encodings = TOKENIZER REGISTRY tokenizer type ⋮---- available = e.value for e in type encodings.keys Evidence: `backend/airweave/adapters/tokenizer/registry.py`
- **Service** (source_file): class AnalyticsService ⋮---- def init self - None ⋮---- def get deployment type self - str ⋮---- """Determine if this is hosted platform or self-hosted deployment. Returns: str: "hosted" for app.airweave.ai, "self hosted" for other deployments Get a unique identifier for this deployment. Returns: str: Unique identifier for the deployment Identify a user with properties. Args: ---- user id: Unique identifier for the user properties: User properties to set Extract distinct id, groups, and metadata from a request context.""" ⋮---- user = getattr ctx, "user", None ⋮---- distinct id = str user.id ⋮---- distinct id = f"api key {ctx.organization.id}" ⋮---- groups = {"organization": str ctx.organiz… Evidence: `backend/airweave/analytics/service.py`
- **Router** (source_file): class TrailingSlashRouter APIRouter ⋮---- path = path :-1 ⋮---- add path = super .api route path, include in schema=include in schema, kwargs ⋮---- alternate path = path + "/" add alternate path = super .api route alternate path, include in schema=False, kwargs ⋮---- def decorator func: DecoratedCallable - DecoratedCallable Evidence: `backend/airweave/api/router.py`
- **Track active SSE connections** (source_file): router = TrailingSlashRouter ⋮---- Track active SSE connections connection id = f"{ctx}:{job id}:{asyncio.get running loop .time }" ⋮---- ps = await pubsub.subscribe "sync job", job id ⋮---- async def event stream - AsyncGenerator str, None ⋮---- last heartbeat = asyncio.get running loop .time heartbeat interval = 30 ⋮---- current time = asyncio.get running loop .time ⋮---- last heartbeat = current time ⋮---- channel = f"sync job state:{job id}" ⋮---- ps = await pubsub.subscribe "sync job state", job id Evidence: `backend/airweave/api/v1/endpoints/sync.py`
- **Limit concurrency to prevent overload** (source_file): class AdminSyncQueryBuilder ⋮---- def init self ⋮---- def with sync ids self, sync ids: List UUID - "AdminSyncQueryBuilder" ⋮---- def with organization id self, organization id: UUID - "AdminSyncQueryBuilder" ⋮---- def with status self, status: str - "AdminSyncQueryBuilder" ⋮---- status enum = SyncStatus status.lower ⋮---- def with source connection filter self, has source connection: bool - "AdminSyncQueryBuilder" ⋮---- def with is authenticated self, is authenticated: bool - "AdminSyncQueryBuilder" ⋮---- def with collection id self, collection id: str - "AdminSyncQueryBuilder" ⋮---- def with source type self, source type: str - "AdminSyncQueryBuilder" ⋮---- def with last job status self,… Evidence: `backend/airweave/core/admin_sync_service.py`
- **AWS S3** (source_file): BANNED PASSWORDS: frozenset str = frozenset ⋮---- BANNED SUPERUSER EMAILS: frozenset str = frozenset ⋮---- MISTRAL DEFAULT BASE URL: str = "https://api.mistral.ai" ⋮---- class Settings BaseSettings ⋮---- PROJECT NAME: str = "Airweave" LOCAL DEVELOPMENT: bool = False LOCAL CURSOR DEVELOPMENT: bool = False ENVIRONMENT: str = Environment.LOCAL FRONTEND LOCAL DEVELOPMENT PORT: int = 8080 ⋮---- DISABLE RATE LIMIT: bool = False FIRST SUPERUSER: str FIRST SUPERUSER PASSWORD: str FIRST SUPERUSER NAME: str = "Admin" ⋮---- AUTH ENABLED: Optional bool = False AUTH0 DOMAIN: Optional str = None AUTH0 AUDIENCE: Optional str = None AUTH0 RULE NAMESPACE: Optional str = None AUTH0 CLIENT ID: Optional str =… Evidence: `backend/airweave/core/config/settings.py`
- **Container** (source_file): @dataclass frozen=True class Container ⋮---- context cache: ContextCache ⋮---- rate limiter: RateLimiter ⋮---- health: HealthServiceProtocol ⋮---- event bus: EventBus ⋮---- pubsub: PubSub ⋮---- webhook publisher: WebhookPublisher webhook admin: WebhookAdmin endpoint verifier: EndpointVerifier webhook service: WebhookServiceProtocol ⋮---- circuit breaker: CircuitBreaker ⋮---- metrics: MetricsService ⋮---- source service: SourceServiceProtocol ⋮---- source registry: SourceRegistryProtocol auth provider registry: AuthProviderRegistryProtocol auth provider service: AuthProviderServiceProtocol entity definition registry: EntityDefinitionRegistryProtocol ⋮---- collection service: CollectionServic… Evidence: `backend/airweave/core/container/container.py`
- **Base** (source_file): class DomainEvent BaseModel ⋮---- model config = ConfigDict frozen=True ⋮---- event type: EventType timestamp: datetime = Field default factory=lambda: datetime.now timezone.utc organization id: UUID Evidence: `backend/airweave/core/events/base.py`
- **Identifiers** (source_file): class TypeActionCounts BaseModel ⋮---- model config = ConfigDict frozen=True ⋮---- inserted: int = 0 updated: int = 0 deleted: int = 0 kept: int = 0 ⋮---- class EntityBatchProcessedEvent DomainEvent ⋮---- event type: EntityEventType = EntityEventType.BATCH PROCESSED ⋮---- sync id: UUID sync job id: UUID collection id: UUID source connection id: UUID source type: str = "" ⋮---- type breakdown: Dict str, TypeActionCounts = Field default factory=dict ⋮---- batch seq: int = 0 batch duration ms: float = 0 billable: bool = True ⋮---- class AccessControlMembershipBatchProcessedEvent DomainEvent ⋮---- """Emitted during ACL membership collection to signal progress. Unlike EntityBatchProcessedEvent w… Evidence: `backend/airweave/core/events/sync.py`
- **Metrics Service** (source_file): class FakeMetricsService MetricsService ⋮---- async def start self, , pool: DbPool - None ⋮---- async def stop self - None Evidence: `backend/airweave/core/fakes/metrics_service.py`
- **Service** (source_file): class HealthService HealthServiceProtocol ⋮---- @property def shutting down self - bool ⋮---- @shutting down.setter def shutting down self, value: bool - None ⋮---- async def check readiness self, , debug: bool - ReadinessResponse ⋮---- all probes = self. critical, self. informational critical names = {p.name for p in self. critical} ⋮---- skipped = DependencyCheck status=CheckStatus.skipped ⋮---- results = await asyncio.gather ⋮---- checks: dict str, DependencyCheck = {} ready = True ⋮---- ready = False ⋮---- async def run probe self, probe: HealthProbe - tuple str, DependencyCheck Exception ⋮---- result = await asyncio.wait for probe.check , timeout=self. timeout ⋮---- @staticmethod def s… Evidence: `backend/airweave/core/health/service.py`
- **Metrics Service** (source_file): class PrometheusMetricsService MetricsService ⋮---- http: HttpMetrics agentic search: AgenticSearchMetrics db pool: DbPoolMetrics ⋮---- async def start self, , pool: DbPool - None ⋮---- async def stop self - None Evidence: `backend/airweave/core/metrics_service.py`
- **Registry** (source_file): class BaseRegistryEntry BaseModel ⋮---- model config = ConfigDict frozen=True ⋮---- short name: str name: str description: str None class name: str ⋮---- EntryT = TypeVar "EntryT", bound=BaseRegistryEntry, covariant=True ⋮---- class RegistryProtocol Protocol EntryT ⋮---- def get self, short name: str - EntryT ⋮---- def list all self - list EntryT Evidence: `backend/airweave/core/protocols/registry.py`
- **Worker Metrics Registry** (source_file): class SyncMetricDetail TypedDict ⋮---- sync id: str sync job id: str org name: str source type: str ⋮---- class SyncWorkerCount TypedDict ⋮---- active and pending worker count: int ⋮---- @runtime checkable class WorkerMetricsRegistryProtocol Protocol ⋮---- def get pod ordinal self - str: ... ⋮---- async def get metrics summary self - dict str, Any : ... ⋮---- async def get per connector metrics self - dict str, dict str, int : ... ⋮---- async def get total active and pending workers self - int: ... ⋮---- async def get detailed sync metrics self - list SyncMetricDetail : ... ⋮---- async def get per sync worker counts self - list SyncWorkerCount : ... Evidence: `backend/airweave/core/protocols/worker_metrics_registry.py`
- **If cron schedule is None, also set next scheduled run to None** (source_file): class CRUDSync CRUDBaseOrganization Sync, SyncCreate, SyncUpdate ⋮---- sync = await super .get db, id=id, ctx=ctx ⋮---- sync = await self.enrich sync with connections db, sync=sync ⋮---- syncs = await super .get multi db, ctx, skip=skip, limit=limit ⋮---- syncs = await self.enrich sync with connections db, sync for sync in syncs ⋮---- enriched syncs = await self.enricher for all db, sync ⋮---- sync ids = sync.id for sync in syncs ⋮---- stmt = result = await db.execute stmt all connections = result.unique .all ⋮---- sync connections = {} ⋮---- sync id = sync connection.sync id ⋮---- enriched syncs = ⋮---- sync dict = { sync. dict } ⋮---- connections = sync connections.get ⋮---- source = conn… Evidence: `backend/airweave/crud/crud_sync.py`
- **Schemas** (source_file): class ACLChangeType str, Enum ⋮---- ADD = "add" REMOVE = "remove" ⋮---- class MembershipChange BaseModel ⋮---- change type: ACLChangeType member id: str = Field description="Email for users, ID for groups" member type: str = Field description="'user' or 'group'" group id: str = Field description="The group this member belongs to" group name: Optional str = None ⋮---- class MembershipTuple BaseModel ⋮---- class AccessContext BaseModel ⋮---- user principal: str = Field description="User principal username or identifier " user principals: List str = Field description="User principals, e.g., 'user:sp admin' " group principals: List str = Field ⋮---- @property def all principals self - Set str ⋮… Evidence: `backend/airweave/domains/access_control/schemas.py`
- **Service** (source_file): class FakeArfService ArfServiceProtocol ⋮---- def init self - None ⋮---- def seed self, sync id: str, entity id: str, entity dict: Dict str, Any - None ⋮---- def seed manifest self, sync id: str, manifest: SyncManifest - None ⋮---- def set error self, error: Exception - None ⋮---- def get calls self, method: str - List tuple ⋮---- def entity count for self, sync id: str - int ⋮---- async def upsert manifest self, sync context: SyncContext, runtime: SyncRuntime - None ⋮---- async def upsert entities self, entities: List BaseEntity , sync context: SyncContext - int ⋮---- sync id = str sync context.sync.id bucket = self. store.setdefault sync id, {} ⋮---- async def delete entities self, entity… Evidence: `backend/airweave/domains/arf/fakes/service.py`
- **=========================================================================** (source_file): class ArfService ArfServiceProtocol ⋮---- def init self, storage: StorageBackend - None ⋮---- @staticmethod def sync path sync id: str - str ⋮---- @staticmethod def manifest path sync id: str - str ⋮---- @staticmethod def entity path sync id: str, entity id: str - str ⋮---- @staticmethod def file path sync id: str, entity id: str, filename: str = "" - str ⋮---- safe filename = staticmethod StoragePaths.safe filename ⋮---- ========================================================================= Entity serialization helpers ⋮---- @staticmethod def get source short name sync context: SyncContext, runtime: SyncRuntime - str ⋮---- source = runtime.source name = getattr source, "short name", ""… Evidence: `backend/airweave/domains/arf/service.py`
- **Fall back to default logger** (source_file): AUTH PROVIDER OPTIONAL FIELDS: frozenset str = frozenset ⋮---- class BaseAuthProvider ABC ⋮---- is auth provider: ClassVar bool = False provider name: ClassVar str = "" short name: ClassVar str = "" auth config class: ClassVar Optional type BaseModel = None config class: ClassVar Optional type BaseModel = None SETTINGS URL: ClassVar str = "" feature flag: ClassVar Optional str = None ⋮---- def init self ⋮---- """Initialize the base auth provider.""" self. logger: Optional Any = None Store contextual logger as instance variable ⋮---- @property def logger self ⋮---- """Get the logger for this auth provider, falling back to default if not set.""" ⋮---- Fall back to default logger ⋮---- def set… Evidence: `backend/airweave/domains/auth_provider/_base.py`
- **------------------------------------------------------------------** (source_file): registry logger = logger.with prefix "AuthProviderRegistry: " .with context ⋮---- class AuthProviderRegistry AuthProviderRegistryProtocol ⋮---- def init self - None ⋮---- def get self, short name: str - AuthProviderRegistryEntry ⋮---- def list all self - list AuthProviderRegistryEntry ⋮---- def get settings url self, short name: str - str None ⋮---- entry = self. entries short name url = entry.settings url or None ⋮---- def build self - None ⋮---- provider classes = ALL AUTH PROVIDERS ⋮---- short name = provider cls.short name ⋮---- entry = self. build entry provider cls ⋮---- ------------------------------------------------------------------ Private helpers ⋮---- @staticmethod def build en… Evidence: `backend/airweave/domains/auth_provider/registry.py`
- **Service** (source_file): class AuthProviderService AuthProviderServiceProtocol ⋮---- connections = await self. connection repo.get by integration type result: list schemas.AuthProviderConnection = ⋮---- async def list metadata self, , ctx: ApiContext - list AuthProviderMetadata ⋮---- enabled features = ctx.organization.enabled features or ⋮---- async def get metadata self, , short name: str, ctx: ApiContext - AuthProviderMetadata ⋮---- entry = self. get registry entry short name ⋮---- connection = await self. get auth provider connection db, readable id=readable id, ctx=ctx ⋮---- entry = self. get registry entry obj in.short name validated auth fields = self. validate auth fields entry, obj in.auth fields ⋮---- int… Evidence: `backend/airweave/domains/auth_provider/service.py`
- **Check if checkout is needed** (source_file): class BillingService BillingServiceProtocol ⋮---- @staticmethod def analyze plan change context: PlanChangeContext - PlanChangeDecision ⋮---- change type = compare plans context.current plan, context.target plan ⋮---- target is paid = is paid plan context.target plan needs payment method = target is paid and not context.has payment method ⋮---- org model = await self. org repo.get by id db, organization id=organization id ⋮---- new price id = self. payment gateway.get price for plan target plan ⋮---- percent off = coupon percent off for yearly prepay target plan idempotency key = f"yearly:{ctx.organization.id}:{target plan.value}" coupon = await self. payment gateway.create or get yearly co… Evidence: `backend/airweave/domains/billing/service.py`
- **Service** (source_file): class BrowseTreeService BrowseTreeServiceProtocol ⋮---- sc = await self. sc repo.get db, source connection id, ctx ⋮---- sc sync id = sc.sync id sc readable collection id = sc.readable collection id sc connection id = sc.connection id ⋮---- sync schema = await self. sync repo.get db, sc sync id, ctx ⋮---- collection obj = await self. collection repo.get by readable id ⋮---- collection schema = schemas.CollectionRecord.model validate ⋮---- connection obj = await self. conn repo.get db, sc connection id, ctx ⋮---- connection schema = schemas.Connection.model validate connection obj, from attributes=True ⋮---- sync job create = SyncJobCreate ⋮---- sync job obj = await self. sync job repo.creat… Evidence: `backend/airweave/domains/browse_tree/service.py`
- **Service** (source_file): class FakeCollectionService ⋮---- def init self - None ⋮---- def seed self, id: UUID, obj: schemas.Collection - None ⋮---- def seed readable self, readable id: str, obj: schemas.Collection - None ⋮---- def set create result self, result: schemas.Collection - None ⋮---- def set delete result self, result: schemas.Collection - None ⋮---- obj = self. readable store.get readable id Evidence: `backend/airweave/domains/collections/fakes/service.py`
- **Snapshot while session is fresh teardown expires all objects via db.expire all** (source_file): class CollectionService CollectionServiceProtocol ⋮---- vd = db obj.vector db deployment metadata base = schemas.CollectionRecord.model validate db obj, from attributes=True ⋮---- result = await self. collection repo.get multi ⋮---- existing = await self. collection repo.get by readable id ⋮---- deployment metadata = await self. deployment metadata repo.get db ⋮---- collection data = collection in.model dump ⋮---- collection = await self. collection repo.create ⋮---- result = self. to response collection ⋮---- """Get a collection by readable ID.""" db obj = await self. collection repo.get by readable id db, readable id, ctx ⋮---- """Update a collection by readable ID.""" ⋮---- updated = awa… Evidence: `backend/airweave/domains/collections/service.py`
- **Service** (source_file): class FakeConnectService ConnectServiceProtocol ⋮---- def init self - None ⋮---- def seed session response self, resp: ConnectSessionResponse - None ⋮---- def seed sources self, sources: List schemas.Source - None ⋮---- def seed connections self, items: List schemas.SourceConnectionListItem - None ⋮---- def seed connection self, id: UUID, conn: Any - None ⋮---- def seed jobs self, jobs: List schemas.SourceConnectionJob - None ⋮---- source = self. source by name.get short name ⋮---- conn = self. connection by id.get connection id ⋮---- conn = self. connection by id.pop connection id, None Evidence: `backend/airweave/domains/connect/fakes/service.py`
- **------------------------------------------------------------------** (source_file): class ConnectService ConnectServiceProtocol ⋮---- """Raise 403 if integration is not in allowed integrations.""" ⋮---- org = await self. org repo.get ⋮---- connection = await self. sc service.get ⋮---- collection = await self. collection repo.get by readable id ⋮---- session id = uuid4 ⋮---- token = make state ⋮---- expires at = datetime.now timezone.utc + timedelta minutes=10 ⋮---- ------------------------------------------------------------------ Source catalog ⋮---- """List available sources, filtered by session restrictions.""" ctx = await self. build context db, session ⋮---- all sources = await self. source service.list ctx ⋮---- all sources = s for s in all sources if s.short name in… Evidence: `backend/airweave/domains/connect/service.py`
- **Base** (source_file): class BaseTextConverter ABC ⋮---- @abstractmethod async def convert batch self, file paths: List str - Dict str, str ⋮---- class HybridDocumentConverter BaseTextConverter ⋮---- def init self, ocr provider: Optional OcrProvider = None - None ⋮---- @abstractmethod async def try extract self, path: str - Optional str ⋮---- @staticmethod def try read as text path: str, max probe bytes: int = 8192 - Optional str ⋮---- probe = f.read max probe bytes ⋮---- control count = sum 1 for b in probe if b Dict str, Optional str ⋮---- results: Dict str, Optional str = {} needs ocr: List str = ⋮---- name = os.path.basename path ⋮---- markdown = await self. try extract path ⋮---- text content = self. try rea… Evidence: `backend/airweave/domains/converters/_base.py`
- **Registry** (source_file): class StubConverter BaseTextConverter ⋮---- def init self, text: str = "fake-markdown" - None ⋮---- async def convert batch self, file paths: List str - Dict str, str ⋮---- class FakeConverterRegistry ConverterRegistryProtocol ⋮---- def for extension self, ext: str - Optional BaseTextConverter ⋮---- def for web self - BaseTextConverter Evidence: `backend/airweave/domains/converters/fakes/registry.py`
- **Registry** (source_file): class ConverterRegistry ConverterRegistryProtocol ⋮---- def init self, ocr provider: Optional OcrProvider = None - None ⋮---- pdf = PdfConverter ocr provider=ocr provider doc = DocConverter ocr provider=ocr provider docx = DocxConverter ocr provider=ocr provider pptx = PptxConverter ocr provider=ocr provider html = HtmlConverter txt = TxtConverter xlsx = XlsxConverter code = CodeConverter ⋮---- ocr adapter = OcrConverterAdapter ocr provider ⋮---- def for extension self, ext: str - Optional BaseTextConverter ⋮---- def for web self - BaseTextConverter Evidence: `backend/airweave/domains/converters/registry.py`
- **Service** (source_file): class FakeIntegrationCredentialService IntegrationCredentialServiceProtocol ⋮---- def init self - None ⋮---- def seed self, credential: DecryptedCredential, record: IntegrationCredential - None ⋮---- cred = self. store.get credential id ⋮---- record = IntegrationCredential dc = DecryptedCredential rid = UUID str record.id ⋮---- record = self. records.get credential.credential id Evidence: `backend/airweave/domains/credentials/fakes/service.py`
- **Service** (source_file): class IntegrationCredentialService IntegrationCredentialServiceProtocol ⋮---- record = await self. repo.get db, credential id, ctx ⋮---- raw = self. encryptor.decrypt record.encrypted credentials ⋮---- credential create = IntegrationCredentialCreateEncrypted ⋮---- """Re-encrypt and persist an updated DecryptedCredential.""" record = await self. repo.get db, credential.credential id, ctx ⋮---- update = IntegrationCredentialUpdate Evidence: `backend/airweave/domains/credentials/service.py`
- **Registry** (source_file): class FakeDenseEmbedderRegistry ⋮---- def init self - None ⋮---- def get self, short name: str - DenseEmbedderEntry ⋮---- def list all self - list DenseEmbedderEntry ⋮---- def list for provider self, provider: str - list DenseEmbedderEntry ⋮---- def seed self, entries: DenseEmbedderEntry - None ⋮---- def clear self - None ⋮---- class FakeSparseEmbedderRegistry ⋮---- def get self, short name: str - SparseEmbedderEntry ⋮---- def list all self - list SparseEmbedderEntry ⋮---- def list for provider self, provider: str - list SparseEmbedderEntry ⋮---- def seed self, entries: SparseEmbedderEntry - None Evidence: `backend/airweave/domains/embedders/fakes/registry.py`
- **Registry** (source_file): registry logger = logger.with prefix "EmbedderRegistry: " .with context ⋮---- class DenseEmbedderRegistry DenseEmbedderRegistryProtocol ⋮---- def init self - None ⋮---- def get self, short name: str - DenseEmbedderEntry ⋮---- def list all self - list DenseEmbedderEntry ⋮---- def list for provider self, provider: str - list DenseEmbedderEntry ⋮---- def build self - None ⋮---- entry = DenseEmbedderEntry ⋮---- class SparseEmbedderRegistry SparseEmbedderRegistryProtocol ⋮---- """In-memory sparse embedder registry, built from manual registration data.""" ⋮---- """Initialize with empty entries.""" ⋮---- def get self, short name: str - SparseEmbedderEntry ⋮---- """Get a sparse embedder entry by sh… Evidence: `backend/airweave/domains/embedders/registry.py`
- The remaining 20 evidence entries are in `AI_CONTEXT_PACK.json` or `EVIDENCE_INDEX.json`.

## Rules the Host AI Must Follow

- **Treat this asset as pre-work context, not a runtime environment.**: The AI Context Pack contains only an evidence-backed understanding of the project, not the project's executable state. Evidence: `README.md`, `connect/README.md`, `examples/README.md`
- **When answering the user, distinguish what can be previewed from what can only be verified after install.**: The consumer value of the pre-install experience comes from reducing bad installs and misjudgments, not from pretending to be a real run. Evidence: `README.md`, `connect/README.md`, `examples/README.md`

## Questions the User Should Answer First

- Which host AI or local environment do you plan to use it in?
- Do you just want to experience the workflow first, or are you ready to actually install?
- What matters most to you: install cost, output quality, or conflicts with your existing rules?

## Acceptance Checks

- Every capability claim can be traced back to a file path in evidence_refs.
- AI_CONTEXT_PACK.md does not package previews as a real run.
- The user can understand who it fits, what it can do, how to start, and the risk boundaries within 3 minutes.

---

## Doramagic Context Augmentation

The following sections strengthen the repository context for a host AI. Human Manual data is a reading route, and pitfall notes become operating constraints.

## Human Manual Outline

Usage rule: this is only a reading route and salience signal, not factual authority. Concrete claims must still return to repo evidence or Claim Graph.

Host AI hard rules:
- Do not treat page titles, section order, summaries, or importance values as factual project evidence.
- When explaining the Human Manual outline, state that it is only a reading route or salience signal.
- Capability, installation, compatibility, runtime state, and risk claims must cite repo evidence, source paths, or Claim Graph.

- **Repository Overview & System Architecture**: importance `high`
  - source_paths: README.md, backend/airweave/main.py, backend/airweave/architecture-refactor.md, backend/airweave/core/container/container.py, backend/airweave/core/config/settings.py
- **Source Connectors, Entities & Sync Pipeline**: importance `high`
  - source_paths: backend/airweave/platform/sources/_base.py, backend/airweave/platform/entities/_base.py, backend/airweave/platform/destinations/vespa/destination.py, backend/airweave/domains/sync_pipeline/orchestrator.py, backend/airweave/domains/syncs/service.py
- **Search, Embeddings, Reranking & Retrieval Layer**: importance `high`
  - source_paths: backend/airweave/search/service.py, backend/airweave/search/orchestrator.py, backend/airweave/domains/search/agentic/service.py, backend/airweave/domains/search/classic/service.py, backend/airweave/domains/search/instant/service.py
- **Authentication Providers, Billing, MCP Server, Connect Widget & Deployment**: importance `high`
  - source_paths: backend/airweave/domains/auth_provider/service.py, backend/airweave/domains/oauth/oauth2_service.py, backend/airweave/domains/billing/service.py, backend/airweave/domains/usage/ledger.py, backend/airweave/domains/source_connections/service.py

## Repo Inspection Evidence

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `1ebe1af2dbfb90f3334410721e69997e4f02b320`
- inspected_files: `README.md`, `examples/README.md`, `examples/quickstart_tutorial.py`, `examples/webhook-demo/README.md`, `examples/webhook-demo/app.py`

Host AI hard rules:
- Without repo_clone_verified=true, do not claim that the source code has been read.
- Without repo_inspection_verified=true, do not write README, docs, or package-file conclusions as facts.
- Without quick_start_verified=true, do not claim that the Quick Start path has run successfully.

## Doramagic Pitfall Constraints

These rules come from Doramagic discovery, validation, or compilation findings. The host AI must treat them as operating constraints, not background notes.

### Constraint 1: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: OneDrive connector appears to continue prefetching after Microsoft account lockout / source state NEEDS_SOURCE
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: OneDrive connector appears to continue prefetching after Microsoft account lockout / source state NEEDS_SOURCE. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may misconfigure credentials, environment, or host setup: OneDrive connector appears to continue prefetching after Microsoft account lockout / source state NEEDS_SOURCE
- Evidence: failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1807
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 2: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: [Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail. Context: Observed when using python
- Why it matters: Developers may misconfigure credentials, environment, or host setup: [Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail
- Evidence: failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1269
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 3: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: [Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing. Context: Observed when using python, docker
- Why it matters: Developers may misconfigure credentials, environment, or host setup: [Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing
- Evidence: failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1801
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 4: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: [Connector Request] neo4j as a source would also be helpful
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [Connector Request] neo4j as a source would also be helpful. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may misconfigure credentials, environment, or host setup: [Connector Request] neo4j as a source would also be helpful
- Evidence: failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1117
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 5: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: [connector support] push
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [connector support] push. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may misconfigure credentials, environment, or host setup: [connector support] push
- Evidence: failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1148
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 6: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: v0.9.64
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.9.64. Context: Observed when using node
- Why it matters: Upgrade or migration may change expected behavior: v0.9.64
- Evidence: failure_mode_cluster:github_release | https://github.com/airweave-ai/airweave/releases/tag/v0.9.64
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 7: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: v0.9.66
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.9.66. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: v0.9.66
- Evidence: failure_mode_cluster:github_release | https://github.com/airweave-ai/airweave/releases/tag/v0.9.66
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 8: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: v0.9.69
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.9.69. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: v0.9.69
- Evidence: failure_mode_cluster:github_release | https://github.com/airweave-ai/airweave/releases/tag/v0.9.69
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.