Metadata-Version: 2.4
Name: carole.ai
Version: 0.1.2
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: keyring>=25.0.0
Requires-Dist: SecretStorage>=3.3.3; sys_platform == "linux"
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-white-bg.png" alt="Carole.ai logo on a white background" width="320" />
</p>


www.caroleai.com



Carole.ai is a local AI agent workspace with chat, project tools, memory, MCP
integrations, browser automation, and a Kanban board. The PyPI package includes
the built web interface: one `caroleai` command runs the FastAPI backend and
serves the frontend from the same address.

The public landing page is [caroleai.com](https://caroleai.com/). 

It does not
host accounts or the backend: Sign in and Sign up open `http://127.0.0.1:8000`
on the visitor's own computer after they install and start Carole.ai.


[![Animated preview of the Carole.ai demo](Demo.webp)](Demo.mp4)

Click the preview to watch the full video with sound.

## Install and run

Use Python 3.11 or 3.12. A virtual environment is recommended:

```bash
python -m venv .venv
# macOS/Linux: source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install carole.ai
caroleai
```

Open [http://127.0.0.1:8000](http://127.0.0.1:8000). The first account created
becomes the local instance owner. Application data is stored in `~/.carole` by
default. Node.js and Docker are **not** required for the PyPI installation.

You can also install the command with `pipx install carole.ai`. To use browser
automation, install the Chromium browser once with `playwright install chromium`.
Connect an AI model provider in the app's settings or supply its API key through
your environment.

To use Google Workspace tools, open **Settings → Google Workspace Integration**
and choose **Connect Google Account**. Carole opens Google's consent page for
the user's own account; no shared Google login is used. Refresh and access
tokens remain on that computer in Windows Credential Manager, macOS Keychain,
or Linux Secret Service. Read operations can run directly, while sending email
or creating, editing, trashing, or deleting Google data requires human approval.

Run `caroleai --help` for options including `--port`, `--data-dir`, and
`--no-browser`. The command binds to `127.0.0.1` by default. Keep it local unless
you have deliberately secured access: the instance owner can use host-level
capabilities such as shell, Git, plugins, and browser automation.

For persistent login sessions, set a stable, random `JWT_SECRET` in your
environment or `.env` file before starting Carole.ai. Without one, a new secret
is generated on each restart and existing sessions are invalidated. Never commit
API keys or secrets to this repository.

## Features

- Hybrid GraphRAG memory with LanceDB and a `networkx` code graph.
- MCP integrations and a dynamic tool registry.
- Gmail, Calendar, Meet, and Google Tasks integration through local OAuth.
- Browser and meeting workflows, including Google Meet integration.
- Real-time Kanban and project-management tools.

## Develop from source

The [public GitHub repository](https://github.com/sshivasai/Carole.ai) contains
both the FastAPI backend and the Next.js frontend. The following is for
contributors working on the source; it is **not** needed to run the PyPI package.

Prerequisites: Python 3.11 or 3.12 and Node.js 22. From the repository root,
create a Python environment and install the backend requirements:

```bash
python -m venv .venv
# Activate .venv for your shell, then:
python -m pip install -r backend/requirements.txt
cd backend
uvicorn main:app --reload
```

In another terminal, start the frontend:

```bash
cd frontend
npm ci
npm run dev
```

The development frontend is at [http://localhost:3000](http://localhost:3000),
the API at [http://localhost:8000](http://localhost:8000), and API documentation
at [http://localhost:8000/docs](http://localhost:8000/docs). Set provider API
keys in your own local environment if you want to use model-backed features.

Source, bug reports, and contributions are available through
[GitHub](https://github.com/sshivasai/Carole.ai) and its
[issue tracker](https://github.com/sshivasai/Carole.ai/issues).

## 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 stored separately per account
in the operating-system credential vault, and any legacy private token file is
migrated and removed. The bundled Desktop OAuth client identifies Carole.ai but
does not grant access to any Google account; access begins only after the user
consents locally. 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.
