otaku 0.1.0__tar.gz

otaku-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+dist/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.idea/
+.claude/
+# private project notes — kept local, never committed
+CLAUDE.md
+.DS_Store
+notes/

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

@@ -0,0 +1,46 @@
+repos:
+  # Lint + format — keep rev in sync with the `ruff` dev dependency
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  # General hygiene
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: detect-private-key
+      - id: check-added-large-files
+        args: [--maxkb=512]
+
+  # Local: type-check against installed deps, plus project guards
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: mypy otaku
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest
+        entry: pytest
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: no-personal-paths
+        name: no /Users/ or /home/ paths in source
+        description: catch absolute home-dir paths leaking into committed files
+        entry: bash -c '! git diff --cached --name-only --diff-filter=ACM | xargs -I{} grep -Hn "/Users/\|/home/" "{}" 2>/dev/null'
+        language: system
+        pass_filenames: false

otaku-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to otaku are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and otaku follows
+[Semantic Versioning](https://semver.org/) — while pre-1.0, minor releases may
+include breaking changes.
+
+## [Unreleased]
+
+Initial release in preparation (`0.1.0`).
+
+### Added
+- Multi-backend client for Ollama, LM Studio, MLX (omlx), and any
+  OpenAI-compatible server — from one terminal command.
+- Cross-provider model management: `otaku list` (with `--running` to show only
+  loaded models), load and unload from the picker, `otaku stop --all`, with a
+  live RAM gauge. Provider queries run concurrently with a short (0.5s) probe
+  timeout, so one configured-but-down provider no longer slows every command;
+  when nothing is reachable, otaku names each provider, whether it answered,
+  and points at `~/.otaku/config.toml` to fix.
+- Chat REPL: streaming responses, thinking-effort control, tok/s stats
+  (`/set verbose`, off by default), triple-quoted multiline input, in-chat
+  model switching (`/model`), `/new` (fresh conversation) vs `/clear` (reset
+  context in place), and slash commands.
+- Streaming markdown rendering: headers, lists, blockquotes, rules, and fenced
+  code blocks (syntax-highlighted via Pygments) on top of inline emphasis/code.
+- omlx output smoothing (`[providers.omlx].smooth`, default on): de-jitters
+  omlx's bursty token delivery into steady typing, without affecting tok/s.
+- Persistent session defaults: a `[defaults]` config section (system, think,
+  parameters, no_record) plus per-model overrides keyed by bare model name;
+  `/remember` saves the current settings as the model's defaults.
+- One-shot / pipe mode: `otaku <model> "prompt"` and `… | otaku <model>`
+  print a plain reply and exit (prompt + stdin combined instruction-first),
+  so otaku works as a Unix filter.
+- Encrypted conversation history (AES-256-GCM), searchable across all
+  conversations by full message content, with background LLM-generated
+  summaries (idle-debounced so they never block exit or reload a cold model;
+  `[defaults].create_summaries` / `summary_idle_seconds`), user-set titles
+  (`/title`, shown in the `/history` picker), and resume-from-any-turn.
+- Get answers out: `/copy` (last reply or whole chat → clipboard, via the native
+  tool or an OSC 52 fallback) and `/save <file>` (conversation → Markdown).
+- Install via `uv tool install` or Homebrew (`brew install enclavum/tap/otaku`).
+- Runs on macOS, Linux, and Windows. On Windows the streaming-time Ctrl+R
+  (cancel + regenerate) shortcut is disabled — it needs a POSIX terminal — but
+  everything else works; WSL gives full parity.

otaku-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing to otaku
+
+otaku is a small, focused project — a terminal chat client for local LLMs.
+Contributions that keep it sharp are very welcome.
+
+## Development setup
+
+otaku uses [uv](https://docs.astral.sh/uv/). With the repo cloned:
+
+```bash
+uv sync --extra dev          # create a venv and install runtime + dev deps
+# or, with pip:
+pip install -e ".[dev]"
+```
+
+Python 3.11+ is required.
+
+## Before opening a PR
+
+The automated safety net is **type-checking + linting**, run on every commit via
+pre-commit:
+
+```bash
+pre-commit install           # one-time: wires ruff + mypy into git hooks
+```
+
+You can run the same checks by hand — or all of them at once with `make check`:
+
+```bash
+make check                   # lint + format-check + mypy + tests (see `make help`)
+
+# …or individually:
+ruff check otaku tests
+ruff format --check otaku tests
+mypy otaku
+pytest
+```
+
+The `Makefile` targets run inside the conda env by default; override with
+`make <target> RUN=` (bare PATH) or `RUN="uv run"`.
+
+### On tests
+
+otaku ships a **full pytest suite** (`tests/`) covering every module — unit
+tests plus CLI tests that drive the typer app end-to-end via
+`typer.testing.CliRunner`. Alongside strict `mypy` + `ruff`, it's the automated
+net; behavioural changes should still be smoke-tested against a real backend
+(Ollama, LM Studio, or an MLX server).
+
+```bash
+pytest                       # whole suite (fast — no network, no real disk)
+pytest tests/test_crypto.py  # one module
+```
+
+Conventions for new tests:
+
+- An autouse `_isolate` fixture (in `tests/conftest.py`) redirects every
+  `~/.otaku` path into a tmp dir, points the DB at a throwaway sqlite file,
+  swaps the OS keychain for an in-memory store, and clears the client cache.
+  **No test may touch the real home directory, keychain, or network.**
+- HTTP is mocked with [`respx`](https://lundberg.github.io/respx/) (the provider
+  layer speaks `httpx`); never hit a live server in a test.
+- Shared, non-fixture helpers live in `tests/support.py` (`make_provider`, the
+  SSE builders, `FakeClient`); import them with `from tests.support import ...`.
+- The TUI pickers are tested by calling their behaviour methods directly — the
+  prompt_toolkit `Application` is never run.
+- When you add a provider, slash command, or KEK provider, add tests for it in
+  the same change (see the "Common tasks" checklists in `CLAUDE.md`).
+
+## Style
+
+- Ruff owns formatting and lint (line length 100) — let it do the work.
+- Keep dependencies minimal: otaku aims to install fast and run anywhere a
+  terminal does. Prefer the standard library; a new runtime dependency needs a
+  real justification.
+- Match the surrounding code: full type hints, `from __future__ import
+  annotations`, small focused modules.
+
+## Reporting bugs and requesting features
+
+Open an issue describing what you ran, what you expected, and what happened —
+including your provider (Ollama / LM Studio / MLX) and the model. For security
+issues, see [SECURITY.md](SECURITY.md) instead of the public tracker.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).

otaku-0.1.0/LICENSE

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

otaku-0.1.0/Makefile

@@ -0,0 +1,55 @@
+# otaku — developer task runner.
+#
+# Commands run inside the project's conda env by default (see CLAUDE.md).
+# Override the runner for other setups, e.g.:
+#     make test RUN=            # use whatever python is on PATH
+#     make test RUN="uv run"    # use uv
+#
+# Pass extra arguments with ARGS=..., e.g.:
+#     make test ARGS="tests/test_crypto.py -x"
+#     make run  ARGS="ollama/llama3"
+
+RUN ?= conda run -n otaku
+SRC := otaku tests
+ARGS ?=
+
+.DEFAULT_GOAL := help
+.PHONY: help install lint format format-check fix typecheck test check run hooks clean
+
+help: ## Show this help
+	@grep -hE '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | \
+		awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-13s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install the package + dev dependencies (editable)
+	$(RUN) pip install -e ".[dev]"
+
+lint: ## Lint with ruff
+	$(RUN) ruff check $(SRC)
+
+format: ## Auto-format with ruff
+	$(RUN) ruff format $(SRC)
+
+format-check: ## Check formatting without writing changes
+	$(RUN) ruff format --check $(SRC)
+
+fix: ## Auto-fix lint issues, then format
+	$(RUN) ruff check --fix $(SRC)
+	$(RUN) ruff format $(SRC)
+
+typecheck: ## Type-check with mypy (strict; otaku/ only)
+	$(RUN) mypy otaku
+
+test: ## Run the test suite (extra args via ARGS=...)
+	$(RUN) python -m pytest $(ARGS)
+
+check: lint format-check typecheck test ## Full pre-flight: lint + format + types + tests
+
+run: ## Run the app (args via ARGS=..., e.g. ARGS="ollama/llama3")
+	$(RUN) otaku $(ARGS)
+
+hooks: ## Run all pre-commit hooks against every file
+	$(RUN) pre-commit run --all-files
+
+clean: ## Remove caches and compiled artifacts
+	rm -rf .pytest_cache .mypy_cache .ruff_cache
+	find $(SRC) -type d -name __pycache__ -prune -exec rm -rf {} +