oi-chat 0.1.0__tar.gz

oi_chat-0.1.0/.env.example

@@ -0,0 +1,12 @@
+# LLM CLI API Keys
+# Copy this file to .env and add your actual API keys
+
+OPENAI_API_KEY=your_openai_api_key_here
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+DEEPSEEK_API_KEY=your_deepseek_api_key_here
+XAI_API_KEY=your_xai_api_key_here
+GEMINI_API_KEY=your_gemini_api_key_here
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+# Optional: Custom chat storage directory
+# LLM_CLI_CHAT_DIR=/path/to/custom/chat/directory

oi_chat-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv run --python ${{ matrix.python-version }} --group dev pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uvx pre-commit run --all-files
+      - run: uv run --group dev ty check

oi_chat-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+# Publishes to PyPI on a version tag (e.g. `git tag v0.1.0 && git push --tags`).
+# Uses PyPI Trusted Publishing (OIDC) — no API tokens stored in the repo.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/oi-chat
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v5
+      - run: uv publish --trusted-publishing always

oi_chat-0.1.0/.gitignore

@@ -0,0 +1,171 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+oi/prompts/*
+!oi/prompts/prompt_general.txt
+!oi/prompts/prompt_concise.txt
+
+# Temporary/scratch files
+tmp.*
+
+# Pre-commit cache
+.pre-commit-cache/

oi_chat-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-case-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

oi_chat-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

oi_chat-0.1.0/AGENTS.md

@@ -0,0 +1,210 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) style:
+
+```
+<type>(<optional scope>): <description>
+```
+
+Common types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`
+
+Examples:
+- `feat(models): add support for Gemini 2.0`
+- `fix(client): handle retry on rate limit errors`
+- `refactor: extract ChatSelector into ui module`
+
+## Development Commands
+
+**Testing:**
+```bash
+uv run pytest                    # Run all tests
+uv run pytest tests/test_main.py # Run specific test file
+```
+
+**Code Quality:**
+```bash
+uv run ty check           # Type checking (ruff formatting/linting handled by pre-commit)
+```
+
+**Installation & Setup:**
+```bash
+# Local development with uv
+uv install
+
+# Install dev dependencies
+uv install --group dev
+
+# Set up pre-commit hooks
+uv run pre-commit install
+
+# Add new dependencies
+uv add <package-name>     # Add a new dependency
+
+# Global installation
+pipx install -e .         # Install from local copy
+pipx install --force -e . # Reinstall after changes
+```
+
+**Running the application:**
+```bash
+uv run oi                      # CLI interface with default settings
+uv run oi -P concise -m sonnet # Use specific prompt and model
+```
+
+## Architecture Overview (Post-Refactoring)
+
+**Directory Structure:**
+```
+src/oi/
+├── core/              # Core business logic
+│   ├── client.py      # LLMClient - API calls & retry logic
+│   ├── session.py     # Chat & ChatMetadata - data models + Chat.create_new()
+│   ├── chat_manager.py # ChatManager - CRUD operations
+│   ├── chat_repository.py # ChatRepository - filesystem persistence
+│   ├── message_utils.py # Message serialization & history helpers
+│   └── smart_title.py # Smart title generation
+├── config/            # Configuration management
+│   ├── settings.py    # Config class + user config (JSON) management
+│   └── loaders.py     # YAML model configuration loading & merging
+├── ui/                # User interface components
+│   ├── input_handler.py # InputHandler - prompt_toolkit integration
+│   ├── chat_selector.py # ChatSelector - interactive chat picker
+│   ├── image_paste.py # PasteStore (images + long text) + PillProcessor + clipboard image reader
+│   └── labels.py      # Shared ANSI/Rich/prompt-toolkit label styling
+├── llm_types.py       # Shared chat/model capability dataclasses
+├── app.py             # Main application orchestration + ChatLoopContext
+├── cli.py             # Command-line argument parsing
+├── main.py            # Entry point (delegates to app.py)
+├── constants.py       # All constants & UI config
+├── exceptions.py      # Custom exception classes
+├── local_commands.py  # Local in-chat slash command registry + completion
+├── prompts.py         # Prompt file loading
+├── registry.py        # ModelRegistry - alias + capability management (single config load)
+└── renderers.py       # Response rendering (StyledRenderer)
+```
+
+**Multi-provider LLM Client:**
+Supports OpenAI, Anthropic, DeepSeek, Google Gemini, xAI, and OpenRouter through Pydantic AI's `direct` APIs with a unified interface.
+
+**Centralized Model Registry:**
+- `ModelRegistry` loads merged config once via `load_merged_model_config()`, then derives both the model map and capabilities from it
+- Providers are "dumb" API clients - no hardcoded model definitions
+- Default model configurable via `aliases.default` in YAML
+- Cross-provider aliases supported
+
+**Model Configuration:**
+- **Minimal default config**: `src/oi/models.yaml` contains only latest SOTA models with date-free aliases
+- **Auto-generated user config**: `~/.config/oi/models.yaml` created on first run from `models_template.yaml`
+- **Deep merge**: User config merges with defaults at model property level (can add just `extra_params` without repeating all capabilities)
+- **YAML anchors**: Top-level keys starting with `_` are ignored (prevents anchors from being treated as providers)
+- **extra_params support**: Model-specific settings (OpenRouter quantization, OpenAI `openai_reasoning_effort`, etc.) merged into `model_settings` before API calls
+- Per-model settings: `max_tokens`, `supports_search`, `supports_thinking`, `supports_vision`, `extra_params`
+
+**Configuration & Prompts:**
+Dual-location system:
+1. User config directory (`~/.config/oi/prompts/`) - takes precedence
+2. Package built-in prompts (`src/oi/prompts/`)
+
+Format: `prompt_[name].txt`, loaded via `prompts.py:read_system_message_from_file()`
+
+**Chat Management:**
+- Rich-based interactive chat selection via `ui/chat_selector.py`
+- Automatic session persistence with metadata in `core/session.py`
+- Smart title generation (triggers after 8+ messages)
+- Auto-save functionality
+
+**Headless Mode:**
+- `-p MESSAGE` sends one turn and exits; composes with `-c` / `-r ID` to follow up against existing chats (appends in-place, same chat ID)
+- `--ephemeral` skips all persistence. Combined with `-c` / `-r` it runs a scratch turn against the existing chat's context without modifying it. Works in interactive mode too — the save gate is in `run_chat_loop` via `ctx.ephemeral`
+- `run_headless_turn()` in `app.py` is the headless entry point; `main()` branches to it when `args.prompt is not None`
+- Output cleanups for pipe-friendliness: `AI:` label hidden via `ChatOptions.show_assistant_label=False`, `Loaded chat:` / "No previous chats" chatter suppressed via `handle_chat_selection(quiet=True)`. Thinking traces still render unless `--hide-thinking` is passed (compose them for clean stdout)
+- `-r` without an ID errors in headless — interactive selector is unavailable
+
+**Streaming & Output:**
+- `StyledRenderer` is the only renderer — provides styled thinking traces (NOT markdown rendering!)
+- Shared label/color definitions live in `ui/labels.py` and are reused by plain prints, Rich output, and the prompt label
+- Rich console with `highlight=False` to prevent number styling in LLM output
+- Real-time streaming with interrupt handling
+
+**Paste Pills (images + long text):**
+- One unified `PasteStore` in `ui/image_paste.py` allocates Unicode PUA sentinel chars for both kinds of pastes; one sentinel per entry so backspace/vim `x`/word motions treat the pill atomically
+- `PillProcessor` expands each sentinel at display time: image sentinels render as `[Image #N] `, text-paste sentinels as `[Paste #N (L lines)] `. Images and pastes are numbered independently, by first occurrence order in the buffer, so deleting one renumbers the rest
+- Image path: `Alt+V` reads the clipboard (via `wl-paste` / `xclip`) and inserts an image sentinel. Binding is only registered when the active model has `supports_vision: true`. `Ctrl+V` is unusable because most terminals (Ghostty, Konsole, iTerm2, …) hijack it for `paste_from_clipboard`
+- Long-text path: `Keys.BracketedPaste` is intercepted in `InputHandler`; pastes that hit `PASTE_LINE_THRESHOLD` (6 lines) **or** `PASTE_CHAR_THRESHOLD` (400 chars) become a single text-paste sentinel, shorter pastes are inserted verbatim. The char limit catches long single-line paragraphs that wrap across many rendered rows. This works around a prompt_toolkit limitation — its diff-based renderer can't progressively commit rows to the scrollback buffer, so any content that scrolls past terminal height gets permanently clobbered. Pills keep the buffer visually short. The pill label still shows lines (source lines match the user's mental model of what they copied, even though chars drive the trigger)
+- On submit, `PasteStore.split()` walks the buffer: text-paste sentinels expand inline into the surrounding text, image sentinels become `BinaryContent` parts. Returns `str` (text-only) or `list[str | BinaryContent]` (mixed). `UserPromptPart` takes either; pydantic-ai passes through to providers
+- `flatten_history` only needs to handle images (text pastes are just text by submit time) — renders `[Image #N]` placeholders for replay of mixed-content messages
+
+**Local Slash Commands:**
+- Local in-chat commands are defined in `local_commands.py`, not inline in `InputHandler`
+- `InputHandler` wires slash command completion through prompt-toolkit
+- Slash command completion uses `CompleteStyle.READLINE_LIKE`, so completion is `Tab`-triggered and rendered in a readline-like way instead of a dropdown menu
+- Unknown slash commands are still rejected in `app.py` after submit so they never get sent to the model
+
+**Key Components:**
+- `LLMClient` (core/client.py) - High-level API client with retry logic
+- `ChatManager` (core/chat_manager.py) - Session persistence & management
+- `Chat`/`ChatMetadata` (core/session.py) - Data models
+- `ChatSelector` (ui/chat_selector.py) - Interactive chat selection
+- `InputHandler` (ui/input_handler.py) - User input handling
+- `local_commands.py` - Slash command definitions + completion helpers
+- `ui/labels.py` - Shared label text and styling helpers
+- `ModelRegistry` (registry.py) - Central model/provider management
+- `ResponseHandler` (response_handler.py) - Streaming coordination
+
+**Main Function Structure:**
+Located in `app.py`, broken into logical functions:
+- `parse_arguments()` - CLI parsing (from cli.py)
+- `setup_configuration()` - Returns a `ChatLoopContext` bundling all components
+- `handle_chat_selection()` - Chat loading
+- `Chat.create_new()` - New session creation (classmethod on `Chat`)
+- `run_chat_loop(chat, ctx)` - Main interaction (takes `ChatLoopContext`)
+- `run_headless_turn(args, ctx, registry)` - Single-turn headless path (used when `-p` is set)
+- `main()` - High-level orchestration
+
+**Key Constants:**
+Mostly centralized in `constants.py`:
+- `MIN_MESSAGES_FOR_SMART_TITLE = 8`
+- `DEFAULT_PAGE_SIZE = 10` 
+- UI navigation keys
+
+Conversation and status labels are centralized in `ui/labels.py`:
+- `USER_LABEL`, `AI_LABEL`, `SYSTEM_LABEL`
+- `INFO_LABEL`, `WARNING_LABEL`, `ERROR_LABEL`
+
+**Common Gotchas:**
+1. Add models to `models.yaml`, not provider classes
+2. `StyledRenderer` is for styled thinking traces, NOT markdown rendering
+3. Default model from YAML `aliases.default`, not hardcoded
+4. No bespoke provider classes—add/update models via YAML aliases instead
+5. Thinking traces:
+   - OpenAI reasoning models automatically receive `openai_reasoning_summary="detailed"` when thinking is enabled so we can render their reasoning summaries.
+   - OpenAI reasoning models also set `openai_reasoning_effort="medium"` by default to satisfy the API requirement.
+   - Anthropic models default to `anthropic_thinking={"type": "adaptive"}` when thinking is enabled (via `setdefault` in client.py). Adaptive thinking means the model decides how much to think.
+   - **Claude Haiku 4.5** overrides this via `extra_params: {anthropic_thinking: {type: enabled, budget_tokens: 2048}}` in `models.yaml` because it still requires the explicit budget.
+   - Google Gemini models default to `google_thinking_config={"include_thoughts": True}` when thinking is enabled so their thoughts stream into the UI.
+6. Reasoning-focused OpenAI models (gpt-5, o-series) should be defined under the `openai-responses` provider section so the Responses API (with thinking traces) is used.
+7. `--search` wires up Pydantic AI's `WebSearchTool` only for providers that support it (OpenAI Responses, Anthropic, Gemini, xAI). OpenRouter models automatically switch to their `:online` variant and add the `web` plugin so search works there too; other providers simply ignore the flag.
+8. Rich console has `highlight=False` to prevent auto-styling numbers
+9. User config functions (`load_user_config`, `update_user_config`) live in `config/settings.py`, not a separate file
+10. Prompts loaded from `src/oi/prompts/` directory, not a Python package
+10. Custom exceptions in `exceptions.py` for proper error handling
+11. Conversation/status label text and colors live in `ui/labels.py`, not `constants.py`
+12. Local slash commands are completed from `local_commands.py`; if you add one, update the command registry there
+13. Slash command completion is readline-like `Tab` completion, not a dropdown selector UI
+14. Paste pills (both images and long text) use Unicode PUA sentinel chars in the input buffer; display-only pill expansion via a prompt_toolkit `Processor`. Text pastes expand inline on submit, images become `BinaryContent` parts. Long-text threshold is a fixed `PASTE_LINE_THRESHOLD` in `input_handler.py` (not a function of terminal size — the true failure mode is rendered-rows vs scrollback, which a source-line threshold can only approximate, so the constant is the honest choice). Don't bind `Ctrl+V` — terminals hijack it for paste
+
+**Quick Tests:**
+```bash
+uv run oi --help   # Smoke test
+uv run python -c "from oi.registry import ModelRegistry; print(list(ModelRegistry().get_available_models().keys()))"  # Test model loading
+
+# Headless e2e smoke — `--ephemeral` guarantees no chat dir is written or modified.
+# Use a cheap/fast model and `--no-thinking` for deterministic, grep-friendly output.
+uv run oi -p "say only the word PONG" --ephemeral -m haiku --no-thinking
+```
+
+Do NOT reach for `-c --ephemeral -p "..."` as a casual smoke test — `-c` loads the user's actual latest chat, so even with `--ephemeral` (no save) you still send their full real conversation to the API and then prompt the model with something unrelated. Waste of tokens, confusing for the model. If you really need to exercise the multi-turn path, create an explicit fixture chat first.

oi_chat-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html);
+while pre-1.0, minor version bumps may include breaking changes (CLI flags,
+config/`models.yaml` format, alias names).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-24
+
+Initial public release.
+
+### Changed
+
+- Rebranded from `llm-cli` to `oi`: command, Python package, config/data
+  directories, and PyPI distribution name (`oi-chat`).
+- Upgraded `pydantic-ai` to 1.100 and migrated from `builtin_tools` to the
+  `native_tools` API.
+- Use the non-deprecated `google` provider prefix (was `google-gla`).
+
+### Added
+
+- PyPI packaging metadata (license, classifiers, project URLs).
+- Support for Python 3.10–3.13.
+
+[Unreleased]: https://github.com/dansclearov/oi/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dansclearov/oi/releases/tag/v0.1.0

oi_chat-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

oi_chat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dan Sclearov
+
+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.