Metadata-Version: 2.4
Name: carole.ai
Version: 0.1.0
Summary: A local AI agent workspace with a FastAPI backend and integrated web UI
Author: Carole.ai
Project-URL: Homepage, https://github.com/sshivasai/Carole.ai
Project-URL: Repository, https://github.com/sshivasai/Carole.ai
Project-URL: Issues, https://github.com/sshivasai/Carole.ai/issues
Keywords: ai,agents,assistant,mcp,fastapi
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: sqlalchemy<2.1,>=2.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: lancedb>=0.5.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: jsonschema<5,>=4.23.0
Requires-Dist: referencing<1,>=0.35.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: PyPDF2>=3.0.0
Requires-Dist: networkx>=3.0.0
Requires-Dist: google-api-python-client>=2.0.0
Requires-Dist: google-auth-httplib2>=0.2.0
Requires-Dist: google-auth-oauthlib>=1.2.0
Requires-Dist: mcp<3,>=1.0.0
Requires-Dist: websockets>=12.0
Requires-Dist: langchain-openai
Requires-Dist: langchain-anthropic
Requires-Dist: langchain-google-genai
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: slowapi>=0.1.9
Requires-Dist: playwright>=1.40.0
Requires-Dist: browser-use
Requires-Dist: python-docx>=1.0.0
Requires-Dist: markitdown>=0.1.7
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: markdownify>=0.14.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: h2>=4.1.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: tree-sitter>=0.26.0
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter-rust>=0.24.0
Requires-Dist: tree-sitter-go>=0.25.0
Requires-Dist: tree-sitter-java>=0.23.0
Requires-Dist: tree-sitter-c>=0.24.0
Requires-Dist: tree-sitter-cpp>=0.23.0
Requires-Dist: tree-sitter-c-sharp>=0.23.0
Requires-Dist: tree-sitter-ruby>=0.23.0
Requires-Dist: tree-sitter-php>=0.24.0
Requires-Dist: tree-sitter-html>=0.23.0
Requires-Dist: tree-sitter-css>=0.25.0
Requires-Dist: tree-sitter-json>=0.24.0
Requires-Dist: tree-sitter-bash>=0.25.0
Requires-Dist: tree-sitter-yaml>=0.7.0
Requires-Dist: tree-sitter-toml>=0.7.0
Requires-Dist: tree-sitter-lua>=0.5.0
Requires-Dist: tree-sitter-markdown>=0.5.0
Requires-Dist: tree-sitter-scala>=0.26.0
Requires-Dist: tree-sitter-kotlin>=1.1.0
Requires-Dist: tree-sitter-swift>=0.7.0
Requires-Dist: tree-sitter-sql>=0.3.0
Requires-Dist: tree-sitter-elixir>=0.3.0
Requires-Dist: tree-sitter-zig>=1.1.0
Requires-Dist: tree-sitter-make>=1.1.0
Requires-Dist: tree-sitter-cmake>=0.7.0
Requires-Dist: model2vec>=0.9.0
Requires-Dist: flashrank>=0.2.10
Requires-Dist: traceloop-sdk>=0.62.0
Requires-Dist: croniter<7,>=6.0.0

<p align="center">
  <img src="https://raw.githubusercontent.com/sshivasai/Carole.ai/master/frontend/public/branding/logo-full-dark-animated.gif" alt="Carole.ai Logo" width="280" />
 
</p>

# Carole.ai

**AI AGENTS. REAL WORK.**

Carole.ai is an advanced AI-powered assistant and development environment with a robust suite of features including Hybrid GraphRAG, zero-cost meeting integration, MCP (Model Context Protocol) expansion, and a native real-time Kanban board.

## Install

Carole.ai includes its production web interface in the Python package, so Node.js
is not required at runtime. Python 3.11 or 3.12 is supported.

```bash
pip install carole.ai
caroleai
```

Carole.ai opens at [http://127.0.0.1:8000](http://127.0.0.1:8000) and stores
persistent application data in `~/.carole`. For an isolated application install,
you can use `pipx install carole.ai`. Browser automation additionally requires
the one-time command `playwright install chromium`.

## Features

- **Hybrid GraphRAG**: Combines Dense (LanceDB) and Sparse memory retrieval, mapped alongside a real-time `networkx` Code Graph for unparalleled context awareness.
- **Zero-Cost Meeting Integration**: Seamlessly integrates with Google Meet via Playwright DOM caption scraping and native chat injection.
- **MCP Expansion**: Features a universal Model Context Protocol firewall and dynamic ToolRegistry, expanding the ecosystem of available models and tools securely.
- **Native Real-Time Kanban**: EventBus-driven split-screen project management for dynamic task tracking and synchronization.

## Local Setup Instructions

Follow these steps to get Carole.ai running locally.

### 1. Prerequisites
- Docker and Docker Compose
- Node.js (v22 recommended)
- Python (v3.11 or later)

### 2. Environment Variables
Create a `.env` file in the root directory (or update the existing one) with the necessary variables. At a minimum, you'll need:

```env
OPENROUTER_API_KEY=your_openrouter_api_key_here
# Optional recovery override. Normally the first account is the local owner.
# CAROLE_OWNER_ID=your_account_uuid
# Add other required API keys or database URLs as needed
```

### 3. Start the Backend (FastAPI)
The backend requires Python and FastAPI. We recommend using a virtual environment.

```bash
cd backend
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload
```

### 4. Start the Frontend (Next.js)
The frontend is built with Next.js. Open a new terminal window to start it.

```bash
cd frontend
npm install
npm run dev
```

### 5. Access the Application
- Frontend: [http://localhost:3000](http://localhost:3000)
- Backend API Docs: [http://localhost:8000/docs](http://localhost:8000/docs)


## Instance owner and upgrade notes

The first account created is automatically the local instance owner. An operator
can optionally set `CAROLE_OWNER_ID` to an account UUID as a recovery override.
The instance owner controls host capabilities:
terminal/shell access, Git, browser automation, plugins, MCP servers, external
workspace paths, and instance settings/model/prompt administration. These
operations are unavailable until an owner is configured. Project ownership alone
does not grant access to the host machine. Host tools run with the backend OS
account's privileges; this is not an OS sandbox for untrusted tenants.

File, search, Git, and history APIs require an owned project UUID. Clients must
use the backend Git API; the former Next.js Git endpoint returns HTTP 410.
Attachments require authenticated downloads. Google accounts must reconnect
through Settings after upgrading: credentials are now stored separately per
account, and the old shared token is not reused. The OAuth start request must
include browser credentials so its callback can verify the initiating browser.

Docker stores application data in the `carole_data` volume at `/data/carole`.
Back up and copy any existing `.carole` data into that volume before switching an
existing deployment; creating the volume does not migrate old data. An explicit
`DATABASE_URL` or `CAROLE_HOME_DIR` override must point to persistent storage.
Playwright browsers are installed at a path available to the non-root app user.

See [runtime repair notes](docs/RUNTIME_REPAIRS.md) for the implementation changes
and verification boundaries.
