Metadata-Version: 2.4
Name: evi-assistant
Version: 0.25.0
Summary: Local-first personal AI assistant — CLI, web, and desktop frontends over a shared agent core.
License: MIT License
        
        Copyright (c) 2026 Evi contributors
        
        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:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/your-user/evi
Project-URL: Source, https://github.com/your-user/evi
Project-URL: Changelog, https://github.com/your-user/evi/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/your-user/evi/issues
Project-URL: Documentation, https://github.com/your-user/evi/tree/main/docs
Keywords: ai,assistant,llm,agent,local,ollama,lm-studio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.40.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: psutil>=5.9
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: email
Requires-Dist: google-auth-oauthlib>=1.2; extra == "email"
Requires-Dist: google-api-python-client>=2.130; extra == "email"
Requires-Dist: msal>=1.28; extra == "email"
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn[standard]>=0.29; extra == "web"
Requires-Dist: sse-starlette>=2.1; extra == "web"
Requires-Dist: httpx>=0.27.0; extra == "web"
Requires-Dist: python-multipart>=0.0.9; extra == "web"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: scheduler
Requires-Dist: apscheduler>=3.10; extra == "scheduler"
Provides-Extra: downloads
Requires-Dist: huggingface_hub>=0.24; extra == "downloads"
Provides-Extra: web-tools
Requires-Dist: duckduckgo_search>=6.0; extra == "web-tools"
Requires-Dist: beautifulsoup4>=4.12; extra == "web-tools"
Provides-Extra: computer
Requires-Dist: pyautogui>=0.9.54; extra == "computer"
Requires-Dist: pillow>=10.0; extra == "computer"
Provides-Extra: stt
Requires-Dist: faster-whisper>=1.0; extra == "stt"
Requires-Dist: sounddevice>=0.4.6; extra == "stt"
Requires-Dist: numpy>=1.26; extra == "stt"
Provides-Extra: pdf
Requires-Dist: PyMuPDF>=1.24; extra == "pdf"
Provides-Extra: index
Requires-Dist: numpy>=1.26; extra == "index"
Provides-Extra: calendar
Requires-Dist: icalendar>=5.0; extra == "calendar"
Requires-Dist: recurring-ical-events>=2.1; extra == "calendar"
Requires-Dist: caldav>=1.3; extra == "calendar"
Provides-Extra: rerank
Requires-Dist: sentence-transformers>=3.0; extra == "rerank"
Provides-Extra: telemetry
Requires-Dist: sentry-sdk>=2.0; extra == "telemetry"
Provides-Extra: e2e
Requires-Dist: playwright>=1.40; extra == "e2e"
Requires-Dist: pytest-playwright>=0.5; extra == "e2e"
Provides-Extra: build-desktop
Requires-Dist: pyinstaller>=6.0; extra == "build-desktop"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# eVi — personal AI assistant

Local-first personal assistant. Chat with a model on **your** hardware,
let it use tools, generate images, automate scheduled tasks, drive your
browser, and reach the same core from a terminal, a web app, or a
native desktop window.

> One Python core, three frontends, no cloud round-trips.

```
       ┌──────────────────────────────┐
       │       evi (core library)     │
       │  Agent · Tools · Memory ·    │
       │  Skills · Hooks · MCP ·      │
       │  Scheduler · Dream · …       │
       └────┬──────────┬──────────┬───┘
            │          │          │
        ┌───▼──┐   ┌───▼──┐   ┌───▼────┐
        │ CLI  │   │ Web  │   │Desktop │
        │      │   │ SSE  │   │ Tauri  │
        └──────┘   └──────┘   └────────┘
```

## Requirements

| Component       | Why                              | Notes                  |
|-----------------|----------------------------------|------------------------|
| **Python 3.11+** | Core runtime                     | 3.12 tested            |
| **Git 2.17+**   | Optional — `evi worktree`        | 2.28+ for `init -b`    |
| **An LLM backend** | One of LM Studio / Ollama / llama-server / any OpenAI-compatible endpoint | LM Studio default |
| **NVIDIA GPU**  | Optional — speeds up local LLMs and ComfyUI image gen | CPU fallback works |

## Quickstart

> **Package name:** the project is **eVi**, but the PyPI distribution is
> **`evi-assistant`** (the bare `evi` name was taken). Once published you'll
> `pip install evi-assistant`; the import package and CLI command are both still
> `evi` (`import evi`, run `evi`). The steps below use an editable install
> from a clone, which doesn't depend on the published name.

```bash
git clone <repo> evi && cd evi
python -m venv .venv
.venv\Scripts\Activate.ps1            # Windows
# source .venv/bin/activate            # Linux / macOS

pip install -e .

# Pick a backend. LM Studio + a tool-capable model is the easiest first run.
# In LM Studio: load qwen2.5-7b-instruct → Developer → Start Server.

evi models recommend                    # honest read on what'll fit
evi chat                                # off you go
```

`/help` inside the REPL lists every slash command (goal tracking, plan
mode, auto-approve, model switching, user-defined templates).

## Three-machine setup

eVi is built to span machines. A typical setup:

| Machine          | Role                | Backend           |
|------------------|---------------------|-------------------|
| AI server (P40)  | LLM host + web UI   | Ollama or llama-server, `evi web` on port 8000 |
| Desktop (16 GB)  | Full power workstation | Local LM Studio |
| Laptop (2 GB)    | Thin client           | Profile points at the AI server |

See [docs/multi-machine.md](docs/multi-machine.md) for the wiring.

## Major commands

```text
evi chat                           Start the REPL
evi web --host 0.0.0.0             Run the FastAPI + SSE web UI
evi dream                          Curate long-term memory from yesterday's chats
evi models recommend / list / use  Hardware-aware model selection
evi models pull <ref>              Pull via Ollama tag or hf:<repo>:<file>
evi schedule add / list / run-now  Cron-style scheduled prompts
evi scheduler                      Foreground daemon for scheduled tasks
evi worktree create <branch>       Spin up a git worktree for parallel work
evi profile add home --backend …   Per-machine config overlays
evi voice listen / speak           STT + TTS
evi mcp list-tools                 Show MCP server-provided tools
evi mcp serve                      Run eVi AS an MCP server (other agents use eVi's tools)
```

## What's built

| Phase | Feature                                          | Status |
|-------|--------------------------------------------------|--------|
| 1     | Foundation, CLI, agent loop, fs/code tools       | ✅     |
| 2     | Gmail / Microsoft 365 email                      | ⏸ deferred |
| 3     | ComfyUI image generation                         | ✅     |
| 4     | FastAPI + SSE web UI                             | ✅     |
| 5     | Tauri desktop shell (local + remote modes)       | ✅     |
| 6     | Persistent memory + scoped subagents             | ✅     |
| 7     | MCP (Model Context Protocol) integration         | ✅     |
| 8     | Skills + scheduled tasks                         | ✅     |
| 9     | Backends, model registry, hardware recommender, profiles | ✅ |
| 10    | EVI.md, slash commands, /goal, plan mode         | ✅     |
| 11    | Hooks, auto mode, git worktrees                  | ✅     |
| 12    | Transcripts, dreaming, web search, voice TTS, computer use | ✅ |
| 13    | STT, web UI parity, polish                       | ✅     |

## Layout

```
evi/                core library
  agent.py          agent loop with permission + hooks
  backends/         LM Studio / Ollama / llama.cpp / OpenAI-compat
  llm/              client + subagent runner
  tools/            built-in tool catalog (fs, code, image, web, voice, …)
  mcp/              MCP client bridge + manager
  memory.py         long-term memory store
  skills.py         user skill packets
  scheduler.py      APScheduler driver
  dream.py          memory-consolidation runner
  hardware.py       GPU + RAM detection
  recommend.py      curated model picks per VRAM
  …
  apps/             frontends that consume the core (shipped in the wheel)
    cli/main.py     Typer CLI
    web/server.py   FastAPI + SSE
    web/static/     chat UI (vanilla JS)
desktop/            Tauri 2 shell (NOT a Python package; local-spawn or EVI_REMOTE_URL)
tests/              pytest
docs/               deeper guides
scripts/            install + dev helpers
```

## Configuration

Per-user config lives in `~/.evi/`. Highlights:

```
~/.evi/
  config.toml         primary settings — backend, tools, auto-approve
  profiles/*.toml     overlay profiles for per-machine config
  memory/*.md         long-term memory; `.attic/` holds soft-deleted entries
  skills/<name>/      installed skill packets (SKILL.md + assets)
  commands/<name>.md  user-defined slash command templates
  scheduled/*.json    saved scheduled prompts
  hooks.toml          before/after_tool_call hooks
  mcp.json            MCP server list
  transcripts/        per-session JSONL (input to dreaming)
  logs/               run logs (dreams, scheduled tasks)
```

See [docs/configuration.md](docs/configuration.md) for the full reference.

## Optional dependency groups

```bash
pip install -e '.[web]'        # FastAPI + uvicorn for `evi web`
pip install -e '.[mcp]'        # Model Context Protocol client
pip install -e '.[scheduler]'  # APScheduler for cron-style tasks
pip install -e '.[downloads]'  # huggingface_hub for `evi models pull hf:...`
pip install -e '.[web-tools]'  # DuckDuckGo search + BeautifulSoup
pip install -e '.[stt]'        # faster-whisper + sounddevice
pip install -e '.[computer]'   # pyautogui for mouse/keyboard control
pip install -e '.[dev]'        # pytest + ruff
```

Or all at once:

```bash
pip install -e '.[dev,web,mcp,scheduler,downloads,web-tools,stt,computer]'
```

## Development

```bash
pip install -e '.[dev]'
pytest -q              # 183 tests, ~12 s
ruff check evi apps    # style + bug-pattern lint
```

See [docs/development.md](docs/development.md) for architecture notes.

## Safety posture

- **Default tool toggles** lean conservative: `shell`, `subagent`, `web`,
  `voice`, `computer`, `gmail`, `outlook`, `image`, and `mcp` are all OFF
  until you flip them in `config.toml`.
- **`auto.auto_approve`** lists categories that run without prompting.
  The defaults are `fs, code, memory, skills, image`. `computer` is never
  in this list — every mouse click / keystroke prompts.
- **Hook vetoes** (`~/.evi/hooks.toml`) can block any tool by glob match.
- **Soft-delete memory** sends "forgotten" entries to `~/.evi/memory/.attic/`
  so the dreaming engine can't permanently lose anything.

## License

MIT (or whatever you prefer — pick when publishing).
