epokio 0.3.0__tar.gz

epokio-0.3.0/LICENSE

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

epokio-0.3.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: epokio
+Version: 0.3.0
+Summary: Watch, compare, queue and report ML training runs (Ultralytics, Hugging Face, Lightning, Keras, TensorBoard) from a menu bar, tray, terminal or web page.
+Author: 8rulerstar
+License-Expression: MIT
+Keywords: machine learning,training,monitoring,ultralytics,yolo,tensorboard,experiment tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: windows-curses; sys_platform == "win32"
+Provides-Extra: tray
+Requires-Dist: pystray>=0.19; extra == "tray"
+Requires-Dist: Pillow>=10.0; extra == "tray"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.2; extra == "mcp"
+Dynamic: license-file
+
+# Epokio
+
+Watch, compare, queue and report machine learning training runs from a web page, a tray icon, a terminal
+or the macOS menu bar. Epokio reads the files your framework already writes, so there is no logging code
+to add, no account and no cloud.
+
+## What it does
+
+* **See every run** on this machine or a remote GPU box: state, epoch, time left, best score, curves,
+  plain-language notes ("recall is much higher than precision…") and the result images your framework saved.
+* **Get told** when a run finishes, fails (NaN loss), stalls or reaches a target score: on the Mac, in the
+  tray, or as a phone push (ntfy, Slack, Discord, Telegram).
+* **Compare runs**: only the settings that differ, a settings table for a whole sweep next to each run's
+  main score, CSV export and Markdown reports.
+* **Start and queue runs** (Ultralytics YOLO) from the web page, one at a time, with a data check before
+  starting, a one-button Python setup (CUDA PyTorch on NVIDIA machines), resume from `weights/last.pt`,
+  and failure causes in plain words.
+* **AI assistants** can read and queue runs through the MCP server (`pip install "epokio[mcp]"`).
+
+Reads Ultralytics (`results.csv`), Hugging Face Trainer (`trainer_state.json`), PyTorch Lightning
+(`metrics.csv`), Keras (`CSVLogger`) and TensorBoard event files (read without TensorFlow). A hand-written
+loop shows up with two lines:
+
+```python
+import epokio
+with epokio.start("runs/my-model", epochs=50, lr=1e-4) as run:
+    for epoch in range(50):
+        ...
+        run.log(val_loss=vl, accuracy=acc)
+```
+
+## Start
+
+```
+pip install epokio
+epokio setup            # finds your runs, starts the helper, opens the page
+epokio setup --lan      # also let your phone or another computer watch this machine
+```
+
+Other commands: `epokio watch` (terminal view, good over SSH), `epokio tray` (`pip install "epokio[tray]"`),
+`epokio doctor` (what Epokio sees, for a bug report), `epokio agent --stop`.
+
+Viewing is open on this machine; anything that starts, stops or changes something needs the machine's token
+(`epokio agent --show-token`). The helper uses only the Python standard library.
+
+MIT licence.

epokio-0.3.0/PYPI.md

@@ -0,0 +1,46 @@
+# Epokio
+
+Watch, compare, queue and report machine learning training runs from a web page, a tray icon, a terminal
+or the macOS menu bar. Epokio reads the files your framework already writes, so there is no logging code
+to add, no account and no cloud.
+
+## What it does
+
+* **See every run** on this machine or a remote GPU box: state, epoch, time left, best score, curves,
+  plain-language notes ("recall is much higher than precision…") and the result images your framework saved.
+* **Get told** when a run finishes, fails (NaN loss), stalls or reaches a target score: on the Mac, in the
+  tray, or as a phone push (ntfy, Slack, Discord, Telegram).
+* **Compare runs**: only the settings that differ, a settings table for a whole sweep next to each run's
+  main score, CSV export and Markdown reports.
+* **Start and queue runs** (Ultralytics YOLO) from the web page, one at a time, with a data check before
+  starting, a one-button Python setup (CUDA PyTorch on NVIDIA machines), resume from `weights/last.pt`,
+  and failure causes in plain words.
+* **AI assistants** can read and queue runs through the MCP server (`pip install "epokio[mcp]"`).
+
+Reads Ultralytics (`results.csv`), Hugging Face Trainer (`trainer_state.json`), PyTorch Lightning
+(`metrics.csv`), Keras (`CSVLogger`) and TensorBoard event files (read without TensorFlow). A hand-written
+loop shows up with two lines:
+
+```python
+import epokio
+with epokio.start("runs/my-model", epochs=50, lr=1e-4) as run:
+    for epoch in range(50):
+        ...
+        run.log(val_loss=vl, accuracy=acc)
+```
+
+## Start
+
+```
+pip install epokio
+epokio setup            # finds your runs, starts the helper, opens the page
+epokio setup --lan      # also let your phone or another computer watch this machine
+```
+
+Other commands: `epokio watch` (terminal view, good over SSH), `epokio tray` (`pip install "epokio[tray]"`),
+`epokio doctor` (what Epokio sees, for a bug report), `epokio agent --stop`.
+
+Viewing is open on this machine; anything that starts, stops or changes something needs the machine's token
+(`epokio agent --show-token`). The helper uses only the Python standard library.
+
+MIT licence.

epokio-0.3.0/README.md

@@ -0,0 +1,376 @@
+<p align="center">
+  <img src="docs/images/icon.png" width="128" alt="Epokio icon">
+</p>
+
+<h1 align="center">Epokio</h1>
+
+<p align="center">
+  See your model training from the macOS menu bar, or from a web page on Windows, Linux and your phone.<br>
+  Start runs, queue them, auto-label images, and read the results without opening a browser.
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#what-it-does">What it does</a> ·
+  <a href="#remote-gpu">Remote GPU</a> ·
+  <a href="#on-windows-linux-or-your-phone">Windows / Linux</a> ·
+  <a href="#한국어">한국어</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="docs/images/popover-light.png" width="360" alt="Menu bar popover, light">
+  <img src="docs/images/popover-dark.png" width="360" alt="Menu bar popover, dark">
+</p>
+
+## Why
+
+Training a model means waiting. You start a run, then keep opening a terminal or a browser tab to see
+whether it is still alive, how many epochs are left, and whether the score is still going up.
+
+Epokio puts that answer one glance away, in the menu bar, and gives beginners a way to start a run
+without writing a command.
+
+* **No code changes.** It reads the files your framework already writes (`results.csv`, `args.yaml`).
+* **Nothing to sign up for.** Everything runs on your machines.
+* **Native macOS.** Follows dark mode, your accent color, Reduce Motion, Increase Contrast.
+
+## Problems it solves
+
+* **"Is my training still running?"** See epoch, time left and best score in the macOS menu bar, without opening a terminal, TensorBoard or a browser tab.
+* **"Tell me when YOLO training finishes."** A notification on your Mac, and a push to your phone (ntfy, Slack, Discord, Telegram), when a run finishes, fails, stalls or reaches a target score.
+* **"Loss became NaN overnight."** Epokio flags diverged runs (NaN loss) and runs that stopped updating, so you do not find out in the morning.
+* **"Which run was better?"** Compare Ultralytics, Hugging Face, PyTorch Lightning, Keras or TensorBoard-logged runs on one chart and in one table.
+* **"Where does my model get it wrong?"** Rank validation images by score and review the worst ones, with labels and predictions drawn on top.
+* **"I have to watch a GPU server over SSH."** `epokio watch` in the terminal, or open the web page from any laptop or phone.
+
+## What it does
+
+### Menu bar
+
+* Progress, time left, and best score of every run, updated live
+* GPU, CPU and memory, like Activity Monitor (Apple Silicon and NVIDIA)
+* A notification when a run **finishes**, **fails** (loss became NaN), **stalls**, or **stops before its last epoch**
+* A calm resting view when nothing is training
+* **Just finished** card at the top: one click to the results
+
+### Results
+
+<p align="center">
+  <img src="docs/images/studio-runs.png" width="620" alt="Run results">
+</p>
+
+Click any run to see what happened, in one place:
+
+* **Scores** at the best epoch: precision, recall, F1, mAP50, mAP50-95, per head (box, pose, mask). Hover for what each one means.
+* **Curves** for loss and scores, live while training runs
+* **What stands out:** plain-language notes with a next step, such as *"Recall is much higher than precision. It finds most objects but raises many false alarms."*
+* **Result images** your framework saved (curves, confusion matrix, predictions next to your labels), also from remote machines
+* **Next steps:** try this model, review its mistakes, train again with the same settings, or resume a stopped run from `weights/last.pt`
+
+**Compare** two to four runs on one chart and in one table. **Notifications** stay in the bell at the top right, so a run that finished overnight is still there in the morning.
+
+<p align="center">
+  <img src="docs/images/studio-compare.png" width="620" alt="Compare runs">
+</p>
+
+### Studio window
+
+<p align="center">
+  <img src="docs/images/studio-train.png" width="620" alt="Studio, new training">
+</p>
+
+**For beginners:** drop your `data.yaml` and Epokio checks it first: missing labels, classes with no examples, a validation set that is too small, very unbalanced classes. No dataset yet? Start with a tiny 8-image sample. Then pick a task (detect, segment, pose, classify), a model size and
+the number of epochs, then press Start.
+
+**For experts:** turn on *Show all settings* to get every training option of your installed Ultralytics
+version, with its description. The list is generated from Ultralytics' own config file, so it stays
+current when Ultralytics updates.
+
+* **Try it:** drop an image and see what your model finds, with class names and confidence. Uses the CPU while a training run is using the GPU.
+* **Datasets:** see your images with their YOLO boxes and pose keypoints drawn on top. Filter by class, find images with no label, flip through with the arrow keys. No separate labeling tool needed.
+* **Review:** find your best and worst images. Labels are drawn in green, predictions in red, so you see at once what the model missed or invented. Mark each one as *model wrong*, *label wrong* or *not sure* with one key, and get a CSV for fixing labels or retraining.
+* **Queue:** runs one job at a time (one GPU), survives restarts, reorder and cancel, live logs
+* **Auto-label:** pick a model and a folder of images. Labels are written to a separate `labels_auto/`
+  folder, so your existing labels are never overwritten. You get a summary of what to review.
+* **Reports:** a Markdown report with a leaderboard, precision, recall, F1 and mAP per head,
+  the charts your framework produced, and plain-language notes such as
+  *"Validation loss bottomed at epoch 32 and rose afterwards. The model may be overfitting."*
+
+<p align="center">
+  <img src="docs/images/studio-datasets.png" width="620" alt="Datasets, labels drawn on images">
+</p>
+
+## Install
+
+> **On Windows or Linux?** Skip to [On Windows, Linux or your phone](#on-windows-linux-or-your-phone). This section is the Mac app.
+
+1. Download `Epokio-x.y.z.dmg` from [Releases](https://github.com/8rulerstar/epokio/releases/latest) and drag Epokio to Applications.
+2. Open it. That is all.
+
+The app carries its own helper (the *agent*) and starts it with any Python 3.10 or later already on your
+Mac (Anaconda, Homebrew or python.org; the Python that comes with Xcode is 3.9, too old). With none, it
+offers to download a small private Python for itself (about 25 MB). It then looks for training folders on its own, and
+opens the Studio window so you can start even if the menu bar icon is hidden behind the notch.
+
+A separate `pip install` is needed only on **other** machines that train, such as a Windows GPU PC
+(see [Remote GPU](#remote-gpu)).
+
+> **First launch:** the app is not notarized yet, so macOS 15 blocks it the first time. Open it once, then go to
+> **System Settings → Privacy & Security**, scroll down and click **Open Anyway** next to Epokio.
+>
+> **Icon missing from the menu bar?** On macOS 26 and later, allow Epokio in
+> **System Settings → Menu Bar**.
+
+### Build from source
+
+```bash
+git clone https://github.com/8rulerstar/epokio && cd epokio
+python3 -m venv .venv && .venv/bin/pip install -e .
+cd mac && ./build_app.sh --dmg        # build/Epokio.app and build/Epokio-x.y.z.dmg
+```
+
+Requires macOS 15 or later and Xcode command line tools. Training itself needs a Python
+environment with `ultralytics` and `torch`. Epokio finds your environments automatically.
+
+## Remote GPU
+
+Train on a Windows or Linux machine, watch from your Mac.
+
+```bash
+# on the training machine
+pip install epokio
+epokio setup --lan --autostart
+```
+
+`epokio setup` finds your training folders, starts the helper without a console window, prints the
+token to paste into the Mac app, and opens the page. `--lan` lets other machines on your network
+reach it; `--autostart` brings the tray back when you log in. Run it again any time, it changes
+nothing that is already right.
+
+Without `--lan` the helper listens on this machine only, which is what you want if you just came
+for the web page and the tray.
+
+`--label lab-07` sets the name this machine shows as (handy when a class or a team watches many
+machines; the default is the computer name). Over SSH, setup prints an `ssh -L` tunnel command
+instead of opening a browser.
+
+The helper answers when you reach it by IP address, `localhost`, or a name whose first part is this
+machine's name (`pc`, `pc.lan`, `pc.tailXXXX.ts.net`; not `pc2.lan`). This blocks DNS-rebinding pages. For any other
+name, set `EPOKIO_ALLOWED_HOSTS=trainer.example,other.name` on this machine, or send the token.
+
+Install it wherever you like. The agent needs no third-party packages, so a small separate
+virtual environment is the safe choice if you would rather not touch the Python your training uses.
+
+* Watching needs no token: runs, scores, curves, notes and result images. Result images are
+  served only from the folders the agent watches.
+* **Everything else needs the token**, including requests that only look like reading: listing your
+  Python environments, reading a training log, and checking a dataset folder all run a process or
+  read outside the watched folders.
+* Use it on your own network only. The agent has no TLS.
+* Korean and other non-ASCII file names are normalized between macOS (NFD) and Windows (NFC),
+  so a path chosen on the Mac is found on the PC.
+
+## On Windows, Linux or your phone
+
+**You do not need a Mac.** Install on the machine that trains, run one command, and you have the
+progress, scores, curves, result images, comparisons and phone alerts.
+
+**Never used a terminal? On Windows:** download `Epokio.exe` from
+[Releases](https://github.com/8rulerstar/epokio/releases/latest) and double-click it. It needs no Python to watch.
+To train from the Train tab, install Python 3.10 or later first; the tab then sets up PyTorch and Ultralytics with one button. Windows SmartScreen may warn about an
+unsigned app the first time: choose **More info → Run anyway**.
+
+**With Python** (3.10 or later; from [python.org](https://www.python.org/downloads/), tick **Add python.exe to PATH**):
+
+```bash
+py -m pip install "epokio[tray]"
+py -m epokio setup --autostart
+```
+
+(If typing `epokio` says "not recognized", use `py -m epokio` instead; it is the same command.)
+
+**On a Linux server (Ubuntu 24.04, no desktop, over SSH):** system `pip` refuses to install
+(PEP 668), so use a small virtual environment:
+
+```bash
+sudo apt install python3-venv
+python3 -m venv ~/.epokio-venv
+~/.epokio-venv/bin/pip install epokio            # no tray needed
+~/.epokio-venv/bin/python -m epokio setup --root /data/runs --autostart
+```
+
+On a machine without a display, `--autostart` writes a systemd user service instead of a tray entry
+and prints the two commands that turn it on. Setup does not open a browser there; it prints an
+`ssh -L 8787:127.0.0.1:8787 <server>` command, and then `http://127.0.0.1:8787/` works on your own
+computer. That tunnel is the safest way in. If you use `--lan` instead and ufw is on, allow your
+network only: `sudo ufw allow from 192.168.0.0/16 to any port 8787 proto tcp`. Runs outside your home
+folder (`/data`, `/mnt`, `/workspace`) are not found on their own, so pass `--root`. To log from your
+own training code with `epokio.start`, install Epokio into the **training** environment too.
+
+That finds your training folders, starts the helper with no console window, opens the page already
+unlocked, and makes the tray come back when you log in. With `--lan`, Windows asks whether Python may
+use the network: tick **Private networks** and click **Allow**, or your phone cannot connect. Turn that last part off again with
+`epokio autostart --off`, or from the tray menu (*Start when I log in*). The entry is an ordinary
+shortcut in your Startup folder, so you can also just delete it.
+
+Review, auto-labelling and the label viewer are in the Mac app only. Everything else here works
+without one:
+
+**Your own training loop.** Not using Ultralytics, Hugging Face, Lightning or Keras? Two lines make it show up like any other run:
+
+```python
+import epokio
+with epokio.start("runs/detr-small", epochs=50, lr=1e-4, batch=16) as run:
+    for epoch in range(1, 51):
+        ...
+        run.log(train_loss=tl, val_loss=vl, precision=p, recall=r, mAP50=m)   # tensors are fine
+```
+
+Logging never stops your training, even when the file is busy. In multi-GPU training only rank 0 writes. In a notebook, use the `with` block or call `run.finish()` after the loop, so the run shows as done; a run that ends with an error is never marked done.
+
+**A web page.** On the training PC open `http://127.0.0.1:8787/` (setup opens it for you). From your phone or another computer, use the address setup printed (needs `--lan`). It works in any browser, to see runs, scores, curves, notes, result images, comparisons and notifications. No install, no account. The **Train** and **Queue** tabs start runs, reorder or remove what is waiting, show each job's log, and stop the one that is running after asking you. Pick what the model should learn and how big it is, and Train fills in the model; it checks the dataset before starting and stops you if it is broken. With no Python for training yet, one button sets one up (with CUDA PyTorch on a PC with an NVIDIA GPU). The queue shows the epoch, time left and finish time of the running job, and when a job fails it says why in plain words and what to change (GPU out of memory, Windows data loader workers, CPU-only PyTorch, wrong dataset paths and more). An Ultralytics run's page has **Train again with these settings**, and a stopped one that did not reach its last epoch also has **Resume**, which continues from `weights/last.pt` in the same folder with the Python that first ran it. On any run's page, **Main score** picks which logged value counts as the score, whether lower is better (loss, error rate), and a target that sends a phone alert when reached; the list, ranking and alerts follow it. **Compare** has a settings table for every run shown (only the settings that differ, next to each run's score, sortable by either, and included in the CSV), and for the runs you pick it shows only the settings that differ, warns when they used different data, filters by name or tag, and exports every run as a CSV. Under **Alerts** you can turn on phone alerts (ntfy, Slack, Discord or Telegram) without the Mac app. On the training PC they open unlocked when you start the page from the tray or setup. On another device they are locked until you paste the machine's token once (setup prints it with `--lan`, or run `py -m epokio agent --show-token`); the token stays in that browser. Train finds the Python environments on the machine (conda, python.org installs, project `.venv`s) and builds its settings from that environment's own Ultralytics.
+
+**A terminal view.** On a server over SSH:
+
+```bash
+epokio watch                               # reads the agent on this machine, or the current folder
+epokio watch --root runs/                  # no agent needed: read a folder directly
+epokio watch --agent http://gpu-pc:8787    # watch another machine
+```
+
+Arrow keys to pick a run, Enter for scores, curves and notes, Tab to switch loss and scores, q to quit.
+
+**A system tray icon on Windows and Linux.** `pip install "epokio[tray]"`, then `epokio tray`. The same learning-curve icon fills with progress, the tooltip shows what you pick (progress, time left, finish time, epoch, best score, GPU), and the menu lists runs and opens the dashboard. It starts the agent for you.
+
+**Phone push.** Add an [ntfy](https://ntfy.sh) address such as `https://ntfy.sh/your-secret-topic` as a webhook (Settings, Notifications) and install the free ntfy app. The training machine pushes to your phone directly, even when your Mac is off. You can also run your own ntfy server.
+
+## Use with AI assistants (MCP)
+
+Epokio ships an MCP server, so Claude, ChatGPT or any MCP client can read your runs and queue jobs.
+
+```bash
+pip install "epokio[mcp]"
+claude mcp add epokio -- epokio-mcp
+```
+
+Then ask things like *"How did last night's training go?"* or *"Auto-label this folder with my best model."*
+
+| Look | Do (your assistant asks you first) |
+|---|---|
+| `list_runs`, `analyze_run`, `system_status`, `queue_status`, `job_log`, `python_envs`, `check_filenames` | `start_training`, `auto_label`, `cancel_job`, `export_report` |
+
+## Commands in plain words (optional)
+
+Turn on **Settings → Assistant** and type what you want in the menu bar: *"retrain coco8 for 100 epochs"*, *"compare coco8 and defect_det"*, *"show me how the bert run did"*. Epokio shows what it understood and waits for you to confirm. It uses [TypeSafe](https://typesafe.ai) Jev with your own API key. Only the sentence and your run names are sent, never data, images, scores or paths. Off by default.
+
+## Supported frameworks
+
+Epokio reads the files your framework already writes. No logging code to add.
+
+| Framework | What it reads | Watch, results, compare | Start runs | Auto-label, review |
+|---|---|---|---|---|
+| Ultralytics YOLO | `results.csv`, `args.yaml` | ✅ | ✅ | ✅ |
+| Hugging Face Trainer | `trainer_state.json` (also inside `checkpoint-*`) | ✅ | script | |
+| PyTorch Lightning | `CSVLogger` `metrics.csv`, `hparams.yaml` | ✅ | script | |
+| Keras | `CSVLogger` file (`training.log`, `history.csv`) | ✅ | script | |
+| TensorBoard logs | `events.out.tfevents.*` scalars (Lightning's default logger, Hugging Face `runs/`), read without TensorFlow | ✅ | script | |
+
+Adding another framework is one small adapter class in `src/epokio/adapters.py`.
+
+## How it compares
+
+| | Epokio | Cloud trackers (W&B, Comet) | Self-hosted trackers (MLflow, ClearML, Aim) | Ultralytics Platform |
+|---|---|---|---|---|
+| Code changes in your training script | **None** | Add logging calls | Add logging calls | Train on their platform |
+| Account or server | **None** | Account | Your own server | Account |
+| Where your data goes | **Stays on your machines** | Their cloud | Your server | Their cloud |
+| Always visible | **Menu bar, terminal, web page** | Browser tab, phone app | Browser tab | Browser tab |
+| Runs you started last week | **Shown right away** | Only if they were logged | Only if they were logged | Only if trained there |
+| Team dashboards, sweeps at scale, cloud GPUs | Basic sweeps only | Yes | Yes | Yes (cloud GPUs) |
+
+Epokio is not trying to replace a team experiment tracker. It is the thing you glance at while training runs on your own Mac or GPU box, with results you can act on right away.
+
+## When something is off
+
+* `epokio doctor` prints what Epokio sees: its version, whether the helper is running (and which version),
+  the folders it watches, the Python environments it found and the last lines of its log. It never prints
+  the token, so you can paste the output into a bug report (`--json` for the raw data).
+* The helper writes `~/.epokio/agent.log` (1 MB, one old copy kept), with the reason behind any error.
+* After upgrading, run `epokio setup` again: it restarts a helper that is still running the old version.
+  `epokio agent --stop` stops the helper on this machine.
+
+## Privacy
+
+Epokio does not send your data anywhere. The app talks only to agents you run.
+Optional webhooks (Slack, Discord, Telegram) send a one-line message when a run finishes, and only
+if you add them.
+
+## Status
+
+Early and moving fast. Things that work today are listed above, and [CHANGELOG.md](CHANGELOG.md) lists
+what changed in each version. Bug reports and ideas are welcome as issues.
+
+The app and the web page speak English and Korean. The app follows your Mac's language (or pick one in Settings → General); the web page follows your browser, with a language button at the top. More languages are on the way as machine drafts, and corrections will be very welcome as issues.
+
+License: [MIT](LICENSE).
+
+---
+
+## 한국어
+
+**Epokio**는 학습 진행 상황을 맥 메뉴바에서 바로 보는 앱입니다. 브라우저를 열 필요도, 학습 코드를 고칠 필요도 없습니다.
+
+* **메뉴바**: 모든 학습의 진행률, 남은 시간, 최고 점수. GPU·CPU·메모리. 끝나거나 실패하거나 멈추면 알림
+* **Studio 창**: 초보자는 `data.yaml`을 끌어다 놓고 시작 버튼만 누르면 됩니다. 전문가는 ultralytics 설정 전부를 설명과 함께 볼 수 있습니다
+* **대기열**: 한 번에 하나씩, 껐다 켜도 이어집니다
+* **오토라벨링**: 결과는 `labels_auto/`에 따로 씁니다. 기존 라벨을 덮어쓰지 않습니다
+* **보고서**: 리더보드, Box·Pose별 P·R·F1·mAP, 자동 해설
+* **원격 GPU**: 윈도우 학습 PC에서 `epokio setup --lan`(자동 시작·토큰 안내까지), 맥에서 확인. 보기만 하는 요청은 토큰 없이 되고, 무언가를 실행하거나 감시 폴더 밖을 읽는 요청은 토큰이 있어야 받습니다
+* **맥↔윈도우 한글 파일명**: NFD·NFC가 달라도 같은 파일로 찾아갑니다
+
+설치: [릴리스](https://github.com/8rulerstar/epokio/releases/latest)에서 `.dmg`를 받아 응용 프로그램 폴더로 끌어다 놓고 열면 끝입니다. 도우미(agent)가 앱 안에 들어 있어 맥에서는 `pip install`이 필요 없습니다.
+윈도우는 같은 곳의 `Epokio.exe`를 받아 두 번 누르면 됩니다(보기만 할 때는 파이썬이 필요 없습니다).
+
+### 맥이 없어도 되는 것
+
+맥 앱은 보는 방법 중 하나입니다. 학습 기계에 agent만 깔면 맥 없이도 이만큼 됩니다.
+
+| | 맥 앱 | 웹 화면 · 트레이 · 터미널 |
+|---|---|---|
+| 진행률·남은 시간·최고 점수 | 있음 | **있음** |
+| 성적·곡선·자동 해설·결과 그림 | 있음 | **있음** (웹) |
+| 학습 비교 | 있음 | **있음** (웹) |
+| 끝났을 때 알림 | 맥 알림 | **폰 푸시**(ntfy·Slack·Discord·텔레그램), 윈도우·리눅스 트레이 알림 |
+| GPU·CPU·메모리 | 있음 | **있음** |
+| 학습 시작·대기열 | 있음 | **있음** (웹, 기계 토큰을 한 번 붙여 넣으면). 파이썬 자동 설치(NVIDIA면 CUDA), 출발 전 데이터 점검, 실패 원인·고칠 방법, 남은 시간, 다시 학습 |
+| 검수·오토라벨링·라벨 보기 | 있음 | 없음 (맥 앱 전용) |
+
+```bash
+pip install "epokio[tray]"
+epokio setup --autostart
+```
+
+`epokio setup` 한 줄이면 됩니다. 학습 폴더를 알아서 찾고, 도우미를 **검은 창 없이** 띄우고,
+브라우저를 열어 줍니다. `--autostart`를 붙이면 로그인할 때 트레이가 다시 뜹니다
+(끄려면 `epokio autostart --off`, 또는 트레이 메뉴의 *Start when I log in*).
+시작프로그램 폴더의 평범한 바로 가기라서 탐색기에서 직접 지워도 됩니다.
+경로를 칠 일도, 플래그를 외울 일도 없습니다. 몇 번을 다시 돌려도 안전합니다.
+
+맥에서 이 기계를 보려면 `--lan`을 더하세요. 그때 토큰이 같이 출력됩니다.
+TLS가 없으니 집·회사 안쪽 네트워크에서만 쓰세요. `--label 실습-07`로 이 PC가 보일 이름을 정할 수 있습니다
+(여러 대를 한꺼번에 볼 때). SSH로 들어온 서버에서는 브라우저 대신 `ssh -L` 터널 명령을 알려 줍니다.
+
+웹 화면은 브라우저 언어를 따라 한국어로 나오고, 위쪽 버튼으로 바꿀 수 있습니다.
+도우미는 IP 주소, `localhost`, 이 PC 이름으로 시작하는 주소(`pc.lan`, Tailscale 이름 등)로 접속하면 답합니다.
+그 밖의 이름으로 쓰려면 이 PC에 `EPOKIO_ALLOWED_HOSTS=이름1,이름2`를 설정하세요(악성 웹페이지의 DNS 리바인딩 막기).
+
+```bash
+epokio tray                       # 트레이 아이콘만 따로
+epokio watch                      # 터미널에서 보기
+```
+
+agent는 외부 패키지를 안 씁니다. 학습용 파이썬을 건드리는 게 걱정되면 **별도 가상환경에 깔아도**
+똑같이 동작합니다. 다른 기계에서 보려면 `--host 0.0.0.0`을 더하고, 그때는 토큰이 필요합니다
+(`epokio-agent --show-token`). TLS가 없으니 집·회사 안쪽 네트워크에서만 쓰세요.

epokio-0.3.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "epokio"
+dynamic = ["version"]                        # src/epokio/__init__.py 의 __version__
+readme = { file = "PYPI.md", content-type = "text/markdown" }   # README는 그림이 상대 경로라 PyPI에서 깨진다
+description = "Watch, compare, queue and report ML training runs (Ultralytics, Hugging Face, Lightning, Keras, TensorBoard) from a menu bar, tray, terminal or web page."
+authors = [{ name = "8rulerstar" }]
+keywords = ["machine learning", "training", "monitoring", "ultralytics", "yolo", "tensorboard", "experiment tracking"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Monitoring",
+]
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = ["windows-curses; sys_platform == 'win32'"]   # 윈도우 파이썬에는 curses가 없다(epokio watch)
+
+[project.optional-dependencies]
+tray = ["pystray>=0.19", "Pillow>=10.0"]     # 윈도우·리눅스 트레이
+mcp  = ["mcp>=2.2"]                          # AI 도우미 연동 (epokio-mcp)
+
+[project.scripts]
+epokio = "epokio.cli:main"
+epokio-tray = "epokio.tray:main"
+epokio-setup = "epokio.onboard:main"        # 시작 메뉴 바로 가기로 부르기 좋게
+epokio-agent = "epokio.agent:main"
+epokio-mcp = "epokio.mcp_server:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = { attr = "epokio.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+epokio = ["web/*.html"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]          # 막 클론한 사람이 설치 없이 pytest 를 바로 돌릴 수 있게

epokio-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

epokio-0.3.0/src/epokio/__init__.py

@@ -0,0 +1,39 @@
+"""Epokio agent. 예전 이름은 TrainBar였다."""
+from __future__ import annotations
+
+from pathlib import Path
+
+# 판 번호는 여기 한 곳(pyproject가 이것을 읽는다). ★설치 정보로 읽어, 맥 앱(PYTHONPATH로 소스를 돌린다)과
+#   exe에서는 'unknown'이거나 따로 깔린 다른 epokio의 판이 나왔다
+__version__ = "0.3.0"
+
+
+def _migrate_home() -> None:
+    """옛 데이터 폴더 ~/.trainbar 를 ~/.epokio 로 한 번 옮긴다(새 폴더가 없을 때만).
+    기록 파일 안의 옛 경로도 새 경로로 고친다(대기열 결과 폴더, 알림함의 학습 위치)."""
+    old, new = Path.home() / ".trainbar", Path.home() / ".epokio"
+    if not old.is_dir() or new.exists():
+        return
+    try:
+        old.rename(new)
+        for f in new.glob("*.json"):
+            text = f.read_text(encoding="utf-8")
+            if "/.trainbar/" in text or "\\\\.trainbar\\\\" in text:
+                f.write_text(text.replace("/.trainbar/", "/.epokio/").replace("\\\\.trainbar\\\\", "\\\\.epokio\\\\"),
+                             encoding="utf-8")
+    except OSError:
+        pass            # 옮기지 못하면 새로 시작한다. 옛 폴더는 그대로 남는다
+
+
+_migrate_home()
+
+
+def version() -> str:
+    """이 코드의 판(맥 앱 판 build_app.sh와 같은 숫자로 맞춘다)"""
+    return __version__
+
+
+def start(folder, epochs=None, **params):
+    """직접 짠 학습 코드용 기록기: `run = epokio.start("runs/exp", epochs=50, lr=1e-4)` 후 `run.log(val_loss=..., acc=...)`"""
+    from .logger import start as _start
+    return _start(folder, epochs, **params)

epokio-0.3.0/src/epokio/__main__.py

@@ -0,0 +1,4 @@
+"""`python -m epokio setup` 처럼 쓴다. ★pip의 Scripts 폴더가 PATH에 없는 윈도우에서는 `epokio`가 '인식되지 않는 명령'이었다"""
+from .cli import main
+
+main()