Metadata-Version: 2.4
Name: kortalk
Version: 0.5.0
Summary: Korvus AI popup: selected text → Claude, OpenAI, local models. Tray, streaming, two languages.
Author: kortalk contributors
License: MIT
Project-URL: Homepage, https://github.com/r4ven-me/kortalk
Keywords: korvus,claude,openai,ollama,clipboard,popup,qt,tray
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Desktop Environment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.5
Requires-Dist: anthropic>=0.40
Requires-Dist: PyYAML>=6.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-qt>=4; extra == "test"
Dynamic: license-file

# kortalk

**Korvus AI popup** — part of the **korvus** family (korserver, korctl, kortalk).
An AI popup for selected text in the spirit of
[Crow Translate](https://crow-translate.github.io/): select text with the
mouse → press a hotkey → a window with the AI response pops up near the
cursor. Lives in the tray, streams responses, supports multiple providers.

## Features

- **Popup near the cursor** — rounded corners, Markdown rendering with
  highlighted code blocks, real-time token streaming, text
  selection/copying. Closes on an outside click or `Escape`.
- **Two-column window** — editable prompt+text on the left, response on the
  right, provider selector in the toolbar, `Ctrl+Enter` to send.
- **Tray** — the application is resident: a monochrome raven (Corvus — the
  korvus emblem), left click = popup with the selection, a menu with the
  prompt library, the window, settings and quit.
- **Global hotkeys inside the application** — assigned in Settings
  (defaults: `Ctrl+Alt+C` popup, `Ctrl+Alt+W` window). Every prompt can
  also get its own hotkey that opens the popup with that prompt.
  X11 — direct XGrabKey interception, Wayland — the system GlobalShortcuts
  portal. No external tools or DE configuration required.
- **Prompt library** — any number of named prompts in Settings; a default
  prompt for the main hotkey, per-prompt hotkeys, any prompt from the tray
  submenu.
- **AI providers**:
  - **Claude Code CLI** — via `claude -p`, no API key (default);
  - **Anthropic API** — official SDK, streaming (API key required);
  - **OpenAI-compatible APIs** — OpenAI, **Ollama**, LM Studio, OpenRouter,
    Groq, DeepSeek and any other service with `/chat/completions`
    (configured with `base URL` + model + key; local servers need no key).
- **Graphical settings** — prompts, hotkeys, theme, font, popup sizes,
  timeouts, a provider manager with keys, autostart at login.
  The config is human-readable YAML (`~/.config/kortalk/config.yaml`).
- **Theme and fonts** — follows the environment theme (Qt) by default,
  optionally Nord Dark / Nord Light.
- **Two interface languages** — English (default) and Russian:
  Settings → General → Language.
- **PRIMARY selection is read natively** via Qt — xclip/xsel/wl-clipboard
  are not needed. Works on X11 and Wayland.

## Installation

```bash
pipx install kortalk
kortalk --check     # diagnostics: providers, tray, PRIMARY selection
```

No system packages or flags like `--system-site-packages` are required —
Qt (PySide6) comes from PyPI. The only external dependency is
[Claude Code CLI](https://docs.claude.com), and only if you use the
`claude-cli` provider.

> The config lives in `~/.config/kortalk/config.yaml` and is edited via
> Settings (or by hand). Configs of older versions (toml/ini) are not used.

## Usage

```bash
kortalk                       # start the daemon (tray + hotkeys)
kortalk --popup               # popup near the cursor (for scripts/external hotkeys)
kortalk "Translate to English:"   # popup with a one-off prompt
kortalk --window              # two-column window (alias: --split)
kortalk --provider ollama     # one-off request through a specific provider
kortalk --settings            # settings
kortalk --quit                # quit the running instance
kortalk --check               # diagnostics
```

The main scenario: `kortalk` starts the daemon, everything else is done
from the tray and via global hotkeys. The CLI flags are kept for scripting —
they are delivered to the running instance instantly over a local socket.

The text is taken from the **PRIMARY selection** — selecting it with the
mouse is enough, no Ctrl+C needed.

## Hotkeys

Assigned in Settings → Hotkeys (per-prompt hotkeys — on the Prompts tab),
work globally:

- **X11** — the application grabs the keys directly (XGrabKey), works in
  any WM/DE without configuration.
- **Wayland** — the XDG Desktop Portal (GlobalShortcuts) is used;
  GNOME/KDE will show a binding confirmation dialog. If the portal is not
  available (minimalist compositors) — use the tray or bind
  `kortalk --popup` to a hotkey in your compositor.

## Provider setup

`kortalk --settings` → Providers tab. Examples:

| Provider | Type | Base URL | Model |
|---|---|---|---|
| Claude Code CLI | claude-cli | — | *(empty = CLI default)* |
| Anthropic API | anthropic | — | `claude-opus-4-8` |
| OpenAI | openai | `https://api.openai.com/v1` | `gpt-4o` |
| Ollama | openai | `http://localhost:11434/v1` | `llama3`, `qwen3`, … |
| LM Studio | openai | `http://localhost:1234/v1` | name of the loaded model |
| OpenRouter | openai | `https://openrouter.ai/api/v1` | anything from the catalog |

The "active provider" is used by default for the popup; in the window the
provider is picked from a dropdown, for one-off requests — with
`--provider <id>`.

## Autostart

Settings → General → "Start at login" — creates
`~/.config/autostart/kortalk.desktop` running `kortalk`.

## Development

```bash
git clone https://github.com/r4ven-me/kortalk && cd kortalk
python -m venv .venv && . .venv/bin/activate
pip install -e '.[test]' ruff
ruff check .                        # linter
QT_QPA_PLATFORM=offscreen pytest    # tests (headless)
QT_QPA_PLATFORM=offscreen kortalk --check   # headless diagnostics
```

Layout: [src/kortalk/](src/kortalk/) — `app.py` (CLI, tray, IPC),
`providers.py` (AI workers), `hotkeys.py` (XGrabKey / portal),
`windows.py` (popup and main window), `settings_dialog.py`, `config.py`,
`theme.py`.

Logs of the running application: `~/.local/state/kortalk/kortalk.log`
(verbose output — the `--debug` flag).

## License

MIT, see [LICENSE](LICENSE).
