lepika 0.1.0__tar.gz

lepika-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,64 @@
+name: Bug report
+description: Something LePika did, or failed to do, on your machine.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. The two command outputs below are what make a bug fixable in one round, so please paste them in full. LePika masks keys and tokens in its logs; still, skim before you paste.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you ran, what you saw, and what you expected instead.
+      placeholder: |
+        I ran `lepika` and picked Express mode. After pulling the model it printed
+        "✗ OpenWebUI did not become ready within 180s". I expected the browser to open.
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `lepika doctor`
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Output of `lepika logs`
+      description: Paste the whole thing; the last lines are usually the useful ones.
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: LePika version
+      description: Output of `lepika --version`.
+      placeholder: lepika 0.1.0
+    validations:
+      required: true
+  - type: dropdown
+    id: mode
+    attributes:
+      label: Mode
+      options:
+        - Express (default, no Docker)
+        - Server (docker compose)
+        - Not sure
+    validations:
+      required: true
+  - type: input
+    id: machine
+    attributes:
+      label: Machine
+      description: OS and version, and the GPU if you have one.
+      placeholder: Windows 11, RTX 4070 · macOS 15, M2 · Ubuntu 24.04, no GPU
+    validations:
+      required: true
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: Model you picked, whether Ollama was already installed, anything unusual about the setup.

lepika-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ollama or OpenWebUI itself
+    url: https://github.com/ollama/ollama/issues
+    about: LePika drives these tools, it doesn't replace them. If the problem is inside the model or the chat UI, their trackers are the right place.

lepika-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Something you want LePika to do.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do, and what gets in the way today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you'd like
+      description: The command or behaviour you have in mind. A rough sketch is fine.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered
+      description: Including doing it by hand with Ollama or OpenWebUI directly.

lepika-0.1.0/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,11 @@
+name: Question
+description: Something unclear about how LePika works.
+labels: ["question"]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: Your question
+      description: If it's about your own setup, the output of `lepika status` and `lepika doctor` helps.
+    validations:
+      required: true

lepika-0.1.0/.github/dependabot.yml

@@ -0,0 +1,7 @@
+# Keeps the SHA-pinned actions in .github/workflows current.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

lepika-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## What
+
+<!-- One or two sentences: what changes, and why. Link the issue if there is one. -->
+
+Closes #
+
+## Checklist
+
+- [ ] Title is a conventional commit (`feat:`, `fix:`, `docs:`, `test:`, `ci:`, `chore:`)
+- [ ] Tests cover the change (the failing test came first)
+- [ ] The gate passes locally: `uv run ruff check . && uv run ruff format --check . && uv run mypy src && uv run pytest -q && uv run bandit -c pyproject.toml -r src -q`
+- [ ] README updated if a command, install line, or the platform table changed
+- [ ] No new runtime dependency (LePika has three: typer, rich, structlog)

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

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Least privilege: these jobs only ever read the checked-out repository.
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync --dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run mypy src
+      - name: Tests
+        run: uv run pytest -q
+      - name: Security audit (code)
+        run: uv run bandit -c pyproject.toml -r src -q
+      - name: Security audit (dependencies)
+        run: uv run pip-audit
+
+  # The suite fakes every external effect, so this is about the platform itself:
+  # paths, signals, file modes, `ps` vs `tasklist`. Lint and types are the same
+  # everywhere and run once, above.
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync --dev
+      - name: Tests
+        run: uv run pytest -q

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

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  # Publishes whatever main holds — for a version whose tag predates this
+  # workflow, or a re-run after a transient PyPI failure.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - name: Tag matches pyproject version
+        if: github.ref_type == 'tag'
+        run: |
+          version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "v${version}" = "${GITHUB_REF_NAME}" || {
+            echo "pyproject.toml says ${version} but the tag says ${GITHUB_REF_NAME}"
+            exit 1
+          }
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # OIDC trusted publishing against the PyPI publisher pinned to this workflow
+    # and the `pypi` environment — no API token exists anywhere.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/lepika/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

lepika-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.python-version
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv — note: uv.lock IS tracked; do not add it here
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Local env / secrets
+.env
+*.local

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

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

lepika-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to LePika
+
+Thanks for helping. LePika is small on purpose: a thin layer of Python that drives
+Ollama, OpenWebUI, and `docker compose`. Read [`docs/architecture.md`](docs/architecture.md)
+first; it lists the design rules a change has to keep.
+
+## Setup
+
+Only git and [uv](https://docs.astral.sh/uv/getting-started/installation/) are needed.
+
+```sh
+git clone https://github.com/MikaelSabuhi/lepika
+cd lepika
+uv sync --dev
+uv run pre-commit install
+uv run pytest -q
+```
+
+The test suite runs in about a second with no network, no Docker, and no real
+processes, because every external effect is an injected callable. New code follows
+the same pattern.
+
+## Making a change
+
+1. Open an issue first for anything bigger than a small fix, so we agree on the shape
+   before you write it.
+2. Work on a branch; `main` only changes through pull requests.
+3. Write the failing test, then the code.
+4. Run the gate before you push. It is the same one CI runs:
+
+   ```sh
+   uv run ruff check . && uv run ruff format --check . && uv run mypy src && uv run pytest -q && uv run bandit -c pyproject.toml -r src -q && uv run pip-audit
+   ```
+
+5. Open the PR. The title is a conventional commit (`feat:`, `fix:`, `docs:`, `test:`,
+   `ci:`, `chore:`); PRs are squash-merged, so that title becomes the commit on `main`.
+   Keep each PR to one change.
+
+## Rules worth knowing before you start
+
+- **Three runtime dependencies** (typer, rich, structlog). Use the standard library for
+  everything else; adding a dependency needs a discussion first.
+- **Every user-facing failure is a `FriendlyError`**: one line saying what went wrong,
+  one line saying what to do. No tracebacks reach the user.
+- **Shell out, don't reimplement.** If Ollama, OpenWebUI, uv, or Docker already do it,
+  LePika calls them.
+- **Secrets never touch argv or logs.** Generated keys go in `0600` files.
+- **The README is part of the product.** A change to a command, an install line, or the
+  platform table updates it in the same PR.
+
+## Reporting a bug
+
+Use the bug report template. `lepika doctor` and `lepika logs` output is what makes a
+report actionable, so please include both.
+
+Security problems go through private reporting instead of an issue — see
+[SECURITY.md](SECURITY.md).

lepika-0.1.0/LICENSE

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

lepika-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: lepika
+Version: 0.1.0
+Summary: LePika — your own AI, at home, in one command
+Project-URL: Homepage, https://github.com/MikaelSabuhi/lepika
+Project-URL: Repository, https://github.com/MikaelSabuhi/lepika
+Project-URL: Issues, https://github.com/MikaelSabuhi/lepika/issues
+Project-URL: Changelog, https://github.com/MikaelSabuhi/lepika/releases
+Author: Mikael Sabuhi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: llm,local-ai,ollama,openwebui,self-host
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.7
+Requires-Dist: structlog>=24.1
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/MikaelSabuhi/lepika/main/docs/assets/logo.png" alt="LePika — a cat in a speech bubble with a terminal prompt" width="220">
+</p>
+
+<h1 align="center">LePika</h1>
+
+<p align="center"><b>One command → local AI chat in your browser.</b><br><i>(luh-PEE-ka)</i></p>
+
+<p align="center">
+  <a href="https://github.com/MikaelSabuhi/lepika/actions/workflows/ci.yml"><img src="https://github.com/MikaelSabuhi/lepika/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/lepika/"><img src="https://img.shields.io/pypi/v/lepika" alt="PyPI"></a>
+  <a href="https://github.com/MikaelSabuhi/lepika/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/MikaelSabuhi/lepika/main/docs/assets/demo.gif" alt="lepika: detect the machine, pick a model, chat UI ready" width="720">
+</p>
+
+Your gaming GPU is already an AI machine. LePika self-hosts LLMs on the hardware you
+already own — Mac (Metal), Linux and Windows (NVIDIA) — with zero configuration. No
+Docker, no API keys, no monthly bill, and nothing you type ever leaves the box.
+
+> Named after Pika, the cat who supervises this project. Like any cat, Pika has
+> everything worth having at home and no use for the cloud. Same idea, for your AI.
+
+## Install
+
+**Mac / Linux**
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/MikaelSabuhi/lepika/main/install.sh | sh
+```
+
+**Windows (PowerShell)**
+
+```powershell
+irm https://raw.githubusercontent.com/MikaelSabuhi/lepika/main/install.ps1 | iex
+```
+
+**Already have [uv](https://docs.astral.sh/uv/)?**
+
+```sh
+uv tool install lepika
+```
+
+Then run `lepika`. It detects your OS, GPU, and RAM, offers the models that actually
+fit your machine, installs [Ollama](https://ollama.com) +
+[OpenWebUI](https://openwebui.com), pulls your pick, and opens the chat UI at
+`http://localhost:3000`.
+
+> LePika installs into `~/.local/bin` — if a new terminal can't find the
+> `lepika` command, add that directory to your `PATH` or restart your shell.
+
+Prefer to read the source first, or hack on it?
+`git clone https://github.com/MikaelSabuhi/lepika && cd lepika && uv run lepika` —
+git and [uv](https://docs.astral.sh/uv/getting-started/installation/) are the only
+prerequisites; uv fetches its own Python.
+
+## What it does
+
+- **Native GPU, no containers** — Apple Metal on macOS, CUDA on Linux/Windows.
+  Ollama arrives via Homebrew, the official install script, or winget; OpenWebUI via
+  `uv tool`. CPU-only machines work too (LePika warns you they'll be slow).
+- **Models that fit** — a curated list filtered to your RAM, so there's no guessing
+  whether a 27B fits in 16 GB.
+- **Any model, one field** — Ollama tags, Hugging Face GGUF builds, or full-weight
+  safetensors repos. [Model guide →](https://github.com/MikaelSabuhi/lepika/blob/main/docs/models.md)
+- **Private by default** — everything listens on `127.0.0.1` until you explicitly run
+  `lepika expose`.
+- **Two modes** — ⚡ **Express** (default): everything native, no Docker.
+  🐳 **Server**: the same thing as one readable `docker compose` stack, for the box
+  under the desk. [Server guide →](https://github.com/MikaelSabuhi/lepika/blob/main/docs/server-mode.md)
+
+LePika reuses an Ollama you already have instead of installing a second copy.
+
+## Everyday commands
+
+| Command | What it does |
+| --- | --- |
+| `lepika` | The setup wizard: detect → pick a model → install → chat |
+| `lepika up` / `lepika down` | Start / stop the local AI stack |
+| `lepika status` | Mode, engine, UI, and default model at a glance |
+| `lepika doctor` | Diagnose the setup; every ✗ has a one-line fix |
+| `lepika logs` | Tail LePika's logs (`--lines`, default 50) |
+| `lepika update` | Upgrade the engine and OpenWebUI — chats kept |
+| `lepika model add [ref]` | Download a model and make it the default (no ref → browse) |
+| `lepika model import <dir>` | Import safetensors weights already on disk |
+| `lepika model list` / `lepika model rm` | List / remove downloaded models |
+| `lepika expose` | Share engine + UI on your network behind a generated key |
+| `lepika connect <url>` | Use an engine on another machine (`--local` to go back) |
+
+Global flags: `--version`, `--mode express|server` (the wizard's, not a per-command
+switch), `--dry-run`, and `--help` on every command.
+
+All state lives in one place: `~/.lepika` — config, logs, and (in Express mode)
+OpenWebUI's own chats and uploads. That is what makes `lepika update` keep your chats.
+Point `LEPIKA_HOME` somewhere else if you prefer.
+
+## Why not just use Ollama directly?
+
+You absolutely can. LePika drives [Ollama](https://ollama.com) and
+[OpenWebUI](https://openwebui.com); it doesn't replace them. What it saves you:
+
+| | By hand | With LePika |
+| --- | --- | --- |
+| First run | Install Ollama, install Python, install open-webui, set `OLLAMA_BASE_URL`, start both, find the port | One command |
+| Choosing a model | Guess, download 20 GB, find out it swaps | A list filtered to the RAM you actually have |
+| Wiring UI ↔ engine | Environment variables, by hand, per shell | Done for you |
+| Something's broken | Two sets of logs, two projects' issue trackers | `lepika doctor`, one fix hint per failure |
+| Staying current | Update each piece separately, per platform | `lepika update` |
+
+If you'd rather run the raw tools, their docs are excellent and LePika gets out of your
+way. Curious what it's doing on your behalf? It's a few files of plain Python in
+[`src/lepika/`](https://github.com/MikaelSabuhi/lepika/tree/main/src/lepika): three dependencies, no magic.
+
+## Requirements
+
+- **Disk** for the models: ~0.5 GB for a tiny one, ~5 GB for a good all-rounder,
+  40 GB+ for the flagships.
+- **8 GB RAM** recommended. Less works: LePika steers you to smaller models.
+- **A GPU is optional.** CPU-only machines run everything, slowly, and LePika says so
+  up front.
+- **macOS:** [Homebrew](https://brew.sh) (without it, LePika points you at the
+  Ollama.app download). **Windows:** winget, which ships with Windows 10/11.
+  Full-weight imports have their own fine print — see the [model guide](https://github.com/MikaelSabuhi/lepika/blob/main/docs/models.md).
+
+## Documentation
+
+- [Model guide](https://github.com/MikaelSabuhi/lepika/blob/main/docs/models.md) — every model-ref shape, full-weight imports, gated repos
+- [Server mode](https://github.com/MikaelSabuhi/lepika/blob/main/docs/server-mode.md) — the compose stack, using a GPU box remotely, security
+- [Architecture](https://github.com/MikaelSabuhi/lepika/blob/main/docs/architecture.md) — design rules and how it's built
+
+## Roadmap
+
+Both modes are v0.1 and work today. Next up: **a published package**, so installing is
+a plain name instead of a repo URL. Star the repo to follow along, or open an issue
+with what you'd want next.
+
+## Contributing
+
+Issues and pull requests are welcome; [CONTRIBUTING.md](https://github.com/MikaelSabuhi/lepika/blob/main/CONTRIBUTING.md) has the short
+version of how a change gets in. Found a security problem?
+[SECURITY.md](https://github.com/MikaelSabuhi/lepika/blob/main/SECURITY.md) says how to report it privately.
+
+```sh
+uv sync --dev && uv run pre-commit install && uv run pytest -q
+```
+
+## License
+
+[MIT](https://github.com/MikaelSabuhi/lepika/blob/main/LICENSE) © Mikael Sabuhi