Metadata-Version: 2.4
Name: vaf
Version: 0.1.0a19
Summary: VAF - Veyllo Agentic Framework: Local AI tool for developers
Author-email: Veyllo GmbH <legal@veyllo.io>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/Veyllo-Labs/VAF
Project-URL: Source, https://github.com/Veyllo-Labs/VAF
Project-URL: Issues, https://github.com/Veyllo-Labs/VAF/issues
Project-URL: Documentation, https://github.com/Veyllo-Labs/VAF/blob/main/docs/EMBEDDING.md
Project-URL: Changelog, https://github.com/Veyllo-Labs/VAF/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSING.md
License-File: NOTICE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: colorama>=0.4.0
Requires-Dist: shellingham>=1.5.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: requests>=2.31.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: PyGithub>=2.1.1
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: markdownify>=1.0.0
Requires-Dist: huggingface_hub[hf_xet]>=0.20.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: openai>=1.12.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: schedule>=1.2.0
Requires-Dist: inquirer>=3.1.0
Requires-Dist: tzdata>=2024.1
Requires-Dist: ruff>=0.1.0
Requires-Dist: jsonschema>=4.18.0
Requires-Dist: packaging>=23.0
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: filelock>=3.12.0
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: pyotp>=2.9.0
Requires-Dist: qrcode[pil]>=7.4.0
Requires-Dist: cryptography>=41.0.0
Provides-Extra: server
Requires-Dist: fastapi>=0.109.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.27.0; extra == "server"
Requires-Dist: websockets>=12.0; extra == "server"
Requires-Dist: pydantic>=2.0.0; extra == "server"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3.2; extra == "discord"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: desktop
Requires-Dist: pystray>=0.19.5; extra == "desktop"
Requires-Dist: pillow>=10.0.0; extra == "desktop"
Requires-Dist: pywebview>=4.3.0; extra == "desktop"
Requires-Dist: pyobjc-framework-Cocoa>=9.0; sys_platform == "darwin" and extra == "desktop"
Requires-Dist: PySide6>=6.7.0; sys_platform == "linux" and extra == "desktop"
Requires-Dist: qtpy>=2.0.0; sys_platform == "linux" and extra == "desktop"
Provides-Extra: memory
Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == "memory"
Requires-Dist: asyncpg>=0.29.0; extra == "memory"
Requires-Dist: pgvector>=0.2.0; extra == "memory"
Requires-Dist: sentence-transformers>=2.2.0; extra == "memory"
Requires-Dist: onnxruntime>=1.16.0; extra == "memory"
Requires-Dist: tokenizers>=0.15.0; extra == "memory"
Requires-Dist: numpy>=1.24.0; extra == "memory"
Requires-Dist: redis>=5.0.0; extra == "memory"
Provides-Extra: speech
Requires-Dist: SpeechRecognition>=3.10.0; extra == "speech"
Requires-Dist: pyaudio>=0.2.14; extra == "speech"
Requires-Dist: sherpa-onnx>=1.13; extra == "speech"
Provides-Extra: browser
Requires-Dist: browser-use>=0.12.9; python_version >= "3.11" and extra == "browser"
Requires-Dist: playwright>=1.49.0; python_version >= "3.11" and extra == "browser"
Provides-Extra: pdf
Requires-Dist: PyPDF2>=3.0.0; extra == "pdf"
Requires-Dist: pdfplumber>=0.11.0; extra == "pdf"
Requires-Dist: pycryptodome>=3.15.0; extra == "pdf"
Requires-Dist: pdf2image>=1.16.0; extra == "pdf"
Requires-Dist: pytesseract>=0.3.10; extra == "pdf"
Provides-Extra: docs
Requires-Dist: python-docx>=1.1.0; extra == "docs"
Requires-Dist: openpyxl>=3.1.0; extra == "docs"
Requires-Dist: python-pptx>=0.6.21; extra == "docs"
Provides-Extra: mail
Requires-Dist: IMAPClient>=3.0.0; extra == "mail"
Requires-Dist: nh3>=0.2.17; extra == "mail"
Requires-Dist: zstandard>=0.22.0; extra == "mail"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Provides-Extra: all
Requires-Dist: vaf[browser,desktop,dev,discord,docs,mail,memory,pdf,server,speech,telegram]; extra == "all"
Dynamic: license-file

# VAF - Veyllo Agentic Framework

```
O))         O))       O))))))))
 O))       O))))      O))
  O))     O))  O))    O))
   O))   O))    O))   O))))))
    O)) O)) )))) O))  O))
     O))))        O)) O))
      O))          O))O))     (OO )
```

An autonomous agent framework built on top of local and cloud LLMs. VAF runs as a desktop application, a headless server, or a terminal interface on Windows, macOS, and Linux.

[![CI](https://github.com/Veyllo-Labs/VAF/actions/workflows/ci.yml/badge.svg)](https://github.com/Veyllo-Labs/VAF/actions/workflows/ci.yml) [![Python](https://img.shields.io/badge/python-3.10--3.13-blue.svg)](https://www.python.org/) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://github.com/Veyllo-Labs/VAF/blob/main/LICENSE) [![Commercial license](https://img.shields.io/badge/Commercial%20license-available-success.svg)](https://github.com/Veyllo-Labs/VAF/blob/main/COMMERCIAL.md)

**Dual-licensed:** free under the [GNU AGPL-3.0](https://github.com/Veyllo-Labs/VAF/blob/main/LICENSE), or a [commercial license](https://github.com/Veyllo-Labs/VAF/blob/main/COMMERCIAL.md) for proprietary/SaaS use without copyleft (`legal@veyllo.io`).

**Requires:** Git to clone, and a container runtime. VAF keeps users, auth, setup and memory in a PostgreSQL/pgvector container, so one is required to finish setup and sign in. All three installers set the engine up for you: Windows installs the free Rancher Desktop, macOS auto-installs the free Colima (or uses Docker Desktop if present), and Linux auto-installs your distro's Docker (systemd + `docker` group). The installer also provisions Python and Node itself.

---

## Start here

Pick your path:

| You want to… | Go to |
|---|---|
| **Run VAF** as a desktop app, server, or terminal | [Installation](#installation) below |
| **Build on VAF** as a library (embed the agent in your app) | [docs/EMBEDDING.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/EMBEDDING.md) · [docs/ARCHITECTURE.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/ARCHITECTURE.md) |
| **Write a tool** (extend the agent, ship it as a pip package) | [vaf/tools/README.md](https://github.com/Veyllo-Labs/VAF/blob/main/vaf/tools/README.md) · [docs/EMBEDDING.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/EMBEDDING.md) |
| **Contribute to the engine** (the core agent loop) | [vaf/core/README.md](https://github.com/Veyllo-Labs/VAF/blob/main/vaf/core/README.md) · [docs/ARCHITECTURE.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/ARCHITECTURE.md) |

### Use it as a library

```bash
pip install --pre vaf
```

```python
from vaf import Agent

agent = Agent(config={"provider": "openai", "api_key_openai": "sk-..."})
print(agent.run("In one short sentence, what is Python?"))
```

The same code runs on a fully local GGUF model (`provider="local"` - no key,
nothing leaves the machine) or any supported API provider (`veyllo`, `openai`,
`anthropic`, `google`, `deepseek`, `openrouter`). The base install is slim;
heavy features are opt-in extras like `vaf[memory]` and `vaf[server]`.
Developer guide: [docs/EMBEDDING.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/EMBEDDING.md) ·
runnable examples: [examples/](https://github.com/Veyllo-Labs/VAF/tree/main/examples/)

---

## Installation

**Windows:**
```powershell
git clone https://github.com/Veyllo-Labs/VAF.git
cd VAF
.\install.bat
```

**macOS / Linux:**
```bash
git clone https://github.com/Veyllo-Labs/VAF.git && cd VAF
chmod +x install.sh && ./install.sh
```

The installer sets up a Python venv, installs all dependencies, prepares the web UI (built on first launch), sets up a container engine for you (Rancher Desktop on Windows, Colima on macOS, your distro's Docker on Linux, or uses an existing one if present), and adds the `vaf` command to your shell.

> New to this, or never used `git`/a terminal? Follow the step-by-step [Installation Guide](https://github.com/Veyllo-Labs/VAF/blob/main/docs/setup/INSTALLATION_GUIDE.md). It covers installing git, where to put the folder, running the installer without admin, and troubleshooting.

On **Linux**, the installer asks once which **installation mode** to use (macOS and Windows always install Desktop mode):
```
[1] Desktop  - personal use, local only, system tray (default)
[2] Server   - always-on service, LAN accessible via HTTPS, starts at boot
```
Choose **[2] Server** for home servers, NAS devices, or any headless machine that should be reachable from other devices. See [docs/setup/SERVER_MODE.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/setup/SERVER_MODE.md) for details.

---

## Quickstart

Confirm the install works with a one-shot prompt:

```bash
vaf prompt "Hello"
```

Then launch the desktop app (system tray + web UI at `http://localhost:3000`) with `vaf tray`, or start an interactive terminal chat with `vaf run`. See [Modes](#modes) for all the ways to run VAF.

---

## Updating

VAF updates in place to the latest published release:

```bash
vaf update           # Stop, fetch the latest release, reinstall, migrate, restart
vaf update check     # Check whether a newer version is available
```

`vaf update` only proceeds from a clean checkout, records a rollback point, and reverts automatically if any step fails. A one-line "update available" hint appears at startup (disable via `update_check_on_start` in `config.json`). Maintainers cutting releases: see [docs/setup/RELEASING.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/setup/RELEASING.md).

---

## Modes

VAF runs in three modes depending on your use case.

### Desktop (recommended for personal use)

The desktop app: system-tray icon + agent window, web UI at `http://localhost:3000`. Easiest start: double-click the **VAF Agent** shortcut the installer created, or run:

```bash
vaf tray       # Start the desktop app (tray + web UI)
```

Or manage it as a background service:

```bash
vaf start      # Start in background
vaf stop       # Stop cleanly
vaf restart    # Restart
vaf status     # Show status
```

**LAN access** (other devices on your network):
```bash
vaf server on      # Bind to 0.0.0.0 with HTTPS
vaf server off     # Back to localhost only
vaf server status  # Show active URLs
```

### Server (always-on, starts at boot)

Installed via the **[2] Server** option. VAF runs as a systemd user service. Use the same commands:

```bash
vaf start      # systemctl --user start vaf
vaf stop       # systemctl --user stop vaf
vaf restart    # systemctl --user restart vaf
vaf status     # systemctl --user status vaf
```

LAN access (HTTPS on port 8443) is always enabled and locked in server mode. See [docs/setup/SERVER_MODE.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/setup/SERVER_MODE.md).

### Terminal (CLI)

Interactive chat in the terminal with themes, session management, and streaming output.

```bash
vaf run                        # Start interactive chat
vaf run --session <id>         # Resume a saved session
vaf run --classic              # Minimal interface (SSH / low-bandwidth)
vaf run --no-web               # Skip starting the web UI
```

One-shot (non-interactive):
```bash
vaf prompt "Explain async/await in Python"
vaf prompt "List modified files" --output-format json
```

### Web UI only

If you want the web interface without the tray:
```bash
vaf run --web
```

---

## Models

VAF works with **local GGUF models** and **cloud APIs**. On first start it downloads the default model and the llama-server backend automatically.

**Local (privacy-first):**
- Any GGUF model (Llama 3, Mistral, Qwen, DeepSeek, etc.)
- GPU acceleration: CUDA on Windows, Vulkan on Linux, Metal on macOS
- Minimum context: 32 768 tokens (enforced; required for tool use)

**Cloud APIs:**
- Veyllo
- OpenAI
- Anthropic 
- Google 
- DeepSeek 
- OpenRouter (100+ models)

Switch provider or model at runtime: press `C` in the chat, or use `/model <name>`.

---

## Features

**Agent & Tools**
- 100+ built-in tools: web search, file system, bash, Python execution, calendar, email, GitHub, and more
- Sub-agents for long-running tasks: Coder, Researcher, Librarian
- Docker sandboxing for untrusted code execution
- Scheduled automations (daily news, reminders, reports)

**Memory**
- Persistent long-term memory with semantic search (pgvector + Redis)
- Auto-compression when context fills up; full history archived and restorable
- Memory graph visualization in the web UI

**Sessions & History**
- Named sessions, saved and searchable
- Git-based snapshot/undo for code changes
- Export sessions to Markdown

**Integrations**
- Telegram, Discord, WhatsApp (bridge mode)
- Google Calendar, Gmail, Google Drive
- GitHub

**Developer**
- Plugin system: drop a `BaseTool` subclass into `vaf/tools/`, auto-discovered at startup
- Custom workflows: place a `WORKFLOW` dict in `~/.vaf/workflows/*.py`, auto-loaded
- MCP (Model Context Protocol) client support

---

## CLI Reference

```bash
vaf start            # Start background service (or: systemctl in server mode)
vaf stop             # Stop background service
vaf restart          # Restart background service
vaf status           # Show service status

vaf run              # Interactive chat (TUI)
vaf prompt "..."     # One-shot prompt
vaf tray             # Background service + web UI (foreground)
vaf server on|off|status

vaf update           # Update to the latest release
vaf update check     # Check if a newer release is available

vaf session list|load|delete|export|search
vaf snapshot create|list|restore|undo
vaf automation list|create|run|enable|disable|delete

vaf scaffold new <template> <name>   # Project templates
vaf generate api|function|class|test|component
vaf automate test|build|lint|format|check
vaf debug explain|trace|fix
vaf git commit --auto

vaf models list|set
vaf theme <name>
vaf install-gpu      # Re-detect and install GPU backend
vaf info             # System info
vaf --version
```

---

## Configuration

All user data lives in `~/.vaf/`:

```
~/.vaf/
├── config.json        # Settings (provider, model, n_ctx, ...)
├── sessions/          # Saved conversations
├── context_archive/   # Compressed conversation history
├── snapshots/         # Code undo history
├── automations/       # Scheduled tasks
└── workflows/         # Custom workflow plugins (*.py)
```

Key config options (`config.json`):

| Key | Default | Description |
|-----|---------|-------------|
| `provider` | `local` | `local`, `veyllo`, `openai`, `anthropic`, `google`, `deepseek`, `openrouter` |
| `n_ctx` | `32768` | Context window (minimum 32 768 for tool use) |
| `gpu_layers` | `99` | Layers to offload to GPU (`0` = CPU only) |
| `web_ui_enabled` | `true` | Start web UI alongside the agent |
| `persist_server` | `false` | Keep llama-server running after VAF exits |

---

## Extending VAF

**Custom tool** - create `vaf/tools/my_tool.py`:
```python
from vaf.tools.base import BaseTool

class MyTool(BaseTool):
    name = "my_tool"
    description = "One-line description the agent uses to decide when to call this."
    parameters = {
        "type": "object",
        "properties": {
            "query": {"type": "string"}
        },
        "required": ["query"]
    }

    def run(self, **kwargs) -> str:
        return f"result for {kwargs['query']}"
```

**Custom workflow** - create `~/.vaf/workflows/my_workflow.py`:
```python
WORKFLOW = {
    "name": "My Workflow",
    "triggers": ["my keyword"],
    "variables": {"topic": "What to process"},
    "steps": [
        {"tool": "web_search", "input": "{topic}", "output": "results"},
        {"tool": "coding_agent", "input": "Based on {results}, write code for {topic}", "output": "code"},
    ],
}
```

Both are auto-discovered at startup, no registration needed.

---

## Platform Notes

| | Windows | macOS | Linux |
|---|---|---|---|
| Desktop mode | Tray icon | Menu bar icon | Headless (no icon) |
| GPU backend | CUDA | Metal | Vulkan |
| Web UI | `localhost:3000` | `localhost:3000` | `localhost:3000` |
| Install | `install.bat` | `install.sh` | `install.sh` |

Linux headless mode requires no display server. See [docs/setup/LINUX_SETUP.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/setup/LINUX_SETUP.md) for details.

---

## Documentation

| Topic | Doc |
|---|---|
| Build on VAF (embed as a library) | [docs/EMBEDDING.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/EMBEDDING.md) |
| Runnable examples (quickstart, events, custom tool) | [examples/](https://github.com/Veyllo-Labs/VAF/tree/main/examples/) |
| FAQ for developers | [docs/FAQ.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/FAQ.md) |
| Architecture (framework vs. harness) | [docs/ARCHITECTURE.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/ARCHITECTURE.md) |
| Configuration reference (all config keys) | [docs/setup/CONFIG_SCHEMA.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/setup/CONFIG_SCHEMA.md) |
| Engine reference (CoreAgent contracts) | [docs/CORE_AGENT.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/CORE_AGENT.md) |
| Observability (events, NDJSON scripting) | [docs/OBSERVABILITY.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/OBSERVABILITY.md) |
| Debugging & logging | [docs/DEBUGGING.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/DEBUGGING.md) |
| Write a tool (BaseTool, pip packaging) | [vaf/tools/README.md](https://github.com/Veyllo-Labs/VAF/blob/main/vaf/tools/README.md) |
| Server mode (LAN, autostart) | [docs/setup/SERVER_MODE.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/setup/SERVER_MODE.md) |
| Linux setup & GPU | [docs/setup/LINUX_SETUP.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/setup/LINUX_SETUP.md) |
| LLM backend (local vs API) | [docs/llm/PROVIDER_MODES.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/llm/PROVIDER_MODES.md) |
| Voice agent (live call) | [docs/agents/VOICE_AGENT.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/agents/VOICE_AGENT.md) |
| Memory system | [docs/memory/MEMORY_SYSTEM.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/memory/MEMORY_SYSTEM.md) |
| Web UI & API reference | [docs/web-ui/WEB_UI.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/web-ui/WEB_UI.md) |
| Context management | [docs/memory/CONTEXT_MANAGEMENT.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/memory/CONTEXT_MANAGEMENT.md) |
| Automations | [docs/platform/AUTOMATIONS.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/platform/AUTOMATIONS.md) |
| Docker services | [docs/setup/DOCKER_SERVICES.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/setup/DOCKER_SERVICES.md) |
| Telegram / Discord / WhatsApp | [docs/integrations/TELEGRAM_INTEGRATION.md](https://github.com/Veyllo-Labs/VAF/blob/main/docs/integrations/TELEGRAM_INTEGRATION.md) |
| Workflows | [vaf/workflows/README.md](https://github.com/Veyllo-Labs/VAF/blob/main/vaf/workflows/README.md) |

---

## Star History

<a href="https://www.star-history.com/?repos=Veyllo-Labs%2FVAF&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Veyllo-Labs/VAF&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Veyllo-Labs/VAF&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Veyllo-Labs/VAF&type=date&legend=top-left" />
 </picture>
</a>

---

## License

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://github.com/Veyllo-Labs/VAF/blob/main/LICENSE) [![Commercial license](https://img.shields.io/badge/Commercial%20license-available-success.svg)](https://github.com/Veyllo-Labs/VAF/blob/main/COMMERCIAL.md)

VAF is **dual-licensed**:

- **Open source - [GNU AGPL-3.0-or-later](https://github.com/Veyllo-Labs/VAF/blob/main/LICENSE)**: free to use, modify, and distribute. If you distribute VAF or run a **modified** version as a network service (SaaS), you must make your source available under the AGPL. Unmodified internal use (even commercial) triggers no disclosure. Building Plugins, Tools, and Workflows on top of VAF is explicitly permitted (Section 7 additional permission).
- **Commercial license**: for embedding VAF in a closed-source product or running a proprietary SaaS without AGPL copyleft. See **[COMMERCIAL.md](https://github.com/Veyllo-Labs/VAF/blob/main/COMMERCIAL.md)**.

See **[LICENSING.md](https://github.com/Veyllo-Labs/VAF/blob/main/LICENSING.md)** for the full dual-licensing explanation (English & German) and how to choose.

**Trademarks & brand:** "VAF", "Veyllo", the VAF logo, and the agent avatar (the living-dot visual identity and its animated states) are trademarks and brand assets of Veyllo GmbH and are **not** covered by the code license. See the "Trademarks and Brand Assets" section in [LICENSING.md](https://github.com/Veyllo-Labs/VAF/blob/main/LICENSING.md).

For commercial and OEM licensing, contact **legal@veyllo.io** · **https://veyllo.io**.
