mikon 0.0.1__tar.gz

mikon-0.0.1/.gitignore

@@ -0,0 +1,16 @@
+documents
+.mikon/
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+node_modules/
+frontend/dist/
+frontend/node_modules/
+mikon/web/index.html
+mikon/web/assets/

mikon-0.0.1/LICENSE

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

mikon-0.0.1/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: mikon
+Version: 0.0.1
+Summary: Self-hosted AI development manager for GPU job execution on your own servers
+Project-URL: Homepage, https://github.com/miko-misa/mikon
+Project-URL: Repository, https://github.com/miko-misa/mikon
+Project-URL: Issues, https://github.com/miko-misa/mikon/issues
+Project-URL: Changelog, https://github.com/miko-misa/mikon/releases
+Author-email: miko-misa <hacnosuke@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: amd,deep-learning,experiment-tracking,gpu,job-management,machine-learning,mlops,nvidia
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: bleach<7,>=6.1
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: markdown<4,>=3.6
+Requires-Dist: nvidia-ml-py<13,>=12.550
+Requires-Dist: psutil<8,>=5.9
+Requires-Dist: pydantic<3,>=2.8
+Requires-Dist: pygments<3,>=2.18
+Requires-Dist: pymdown-extensions<11,>=10.11
+Requires-Dist: sse-starlette<4,>=2.1
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: uvicorn[standard]<1,>=0.30
+Requires-Dist: watchfiles<2,>=0.22
+Description-Content-Type: text/markdown
+
+# mikon
+
+> 日本語版: [README-ja.md](README-ja.md)
+
+A self-hosted tool for managing AI development (training and evaluation jobs) on GPU servers from a browser.
+
+**Write Python the way you normally would, and just add a decorator to your functions.** mikon automatically discovers your jobs, generates config forms, allocates GPUs, launches runs, and displays metrics, logs, and artifacts in real time.
+
+---
+
+## Features
+
+- **Decorator-only discovery** — Just add `@mikon.job`. No registration step, no code changes required.
+- **Auto-generated config UI** — Pydantic fields on `class Config(mikon.Config)` become form widgets automatically (sliders, selects, checkboxes, etc.)
+- **NVIDIA and AMD support** — Specify GPUs in unified `nvidia:0` / `amd:0` format. `CUDA_VISIBLE_DEVICES` / `ROCR_VISIBLE_DEVICES` are set automatically.
+- **Live monitoring** — Metric charts and log streams update every few seconds via SSE.
+- **Artifact management** — Call `ctx.log_artifact()` to make files downloadable from the browser.
+- **Lineage tracking** — `ctx.use_dataset()` / `ctx.use_artifact()` automatically build an upstream/downstream graph.
+- **Module system** — Register swappable components with `@mikon.module`; the UI generates a module-selection form automatically.
+- **Dataset management** — Register existing paths or create datasets with a builder function.
+- **Document viewer** — Markdown, Typst, and TypMark files placed in `docs/` are viewable in the dashboard.
+- **File-based persistence** — No SQL database required. Everything is stored as text files under `.mikon/`.
+- **Independent processes** — Jobs keep running even if the dashboard is restarted.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- GPU server with NVIDIA drivers or AMD ROCm installed
+- `typst` CLI (optional, for Typst document rendering)
+- `typmark-cli` CLI (optional, for TypMark document rendering)
+
+---
+
+## Quick Start
+
+```bash
+# Install
+uv add mikon   # or: pip install mikon
+
+# Initialize project
+mikon init
+```
+
+```python
+# src/train.py
+import mikon
+from mikon import Config, RunContext
+from pydantic import Field
+from typing import Literal
+
+class TrainConfig(Config):
+    lr: float = Field(1e-3, gt=0, le=1)
+    epochs: int = Field(10, ge=1, le=1000)
+    optimizer: Literal["adam", "sgd"] = "adam"
+
+@mikon.job
+def train(config: TrainConfig, ctx: RunContext) -> None:
+    for epoch in range(config.epochs):
+        loss = 1.0 / (epoch + 1)
+        ctx.log_metric("loss", loss, step=epoch)
+```
+
+```bash
+# Start the server on the GPU machine
+mikon serve
+
+# Launch a job from the CLI
+mikon run train --gpu nvidia:0
+
+# Access the dashboard from your local machine via SSH port forwarding
+ssh -L 8000:localhost:8000 you@gpu-server
+# → Open http://localhost:8000 in your browser
+```
+
+---
+
+## Installation
+
+```bash
+uv add mikon   # recommended
+pip install mikon
+```
+
+Dependencies (`pynvml`, `psutil`, `watchfiles`, `fastapi`, etc.) are installed automatically.
+
+---
+
+## Documentation
+
+For the full usage guide, SDK reference, CLI options, and API error model, see [USAGE.md](USAGE.md).
+
+---
+
+## License
+
+MIT

mikon-0.0.1/README-ja.md

@@ -0,0 +1,98 @@
+# mikon
+
+> English: [README.md](README.md)
+
+GPUサーバー上のAI開発（学習・評価ジョブ）をブラウザで管理するセルフホスト型ツール。
+
+**あなたは普段どおりPythonでコードを書き、関数にデコレータを付けるだけ。** ツールが自動でジョブを認識し、コンフィグのフォームを生成し、GPUを割り当てて起動し、メトリクス・ログ・成果物をリアルタイムで表示します。
+
+---
+
+## 特徴
+
+- **デコレータだけで認識** — `@mikon.job` を付けるだけ。登録作業やコード変更は不要
+- **コンフィグUIの自動生成** — `class Config(mikon.Config)` の Pydantic フィールドがそのままフォームになる（スライダ・セレクト・チェックボックスなど）
+- **NVIDIA / AMD 両対応** — `nvidia:0` / `amd:0` の統一形式でGPUを指定。`CUDA_VISIBLE_DEVICES` / `ROCR_VISIBLE_DEVICES` を自動設定
+- **ライブモニタリング** — メトリクスチャート・ログストリームが数秒更新（SSE）
+- **成果物管理** — `ctx.log_artifact()` でブラウザからダウンロード可能
+- **リネージュ追跡** — `ctx.use_dataset()` / `ctx.use_artifact()` で上流/下流グラフを自動構築
+- **モジュールシステム** — 差し替え可能なコンポーネントを `@mikon.module` で登録、UIでモジュール選択フォームが自動生成
+- **データセット管理** — 既存パスの登録、ビルダーによる自動作成
+- **ドキュメント閲覧** — `docs/` に置いた Markdown / Typst / TypMark をダッシュボードで表示
+- **ファイルベース永続化** — SQLデータベース不要。すべて `.mikon/` 以下のテキストファイルに保存
+- **独立プロセス** — ダッシュボードを再起動してもジョブは生き続ける
+
+---
+
+## 要件
+
+- Python 3.11+
+- GPUサーバー（NVIDIA ドライバ or AMD ROCm 導入済み）
+- Typst ドキュメントを使う場合は `typst` CLI（任意）
+- TypMark ドキュメントを使う場合は `typmark-cli` CLI（任意）
+
+---
+
+## クイックスタート
+
+```bash
+# インストール
+uv add mikon   # または pip install mikon
+
+# プロジェクト初期化
+mikon init
+```
+
+```python
+# src/train.py
+import mikon
+from mikon import Config, RunContext
+from pydantic import Field
+from typing import Literal
+
+class TrainConfig(Config):
+    lr: float = Field(1e-3, gt=0, le=1)
+    epochs: int = Field(10, ge=1, le=1000)
+    optimizer: Literal["adam", "sgd"] = "adam"
+
+@mikon.job
+def train(config: TrainConfig, ctx: RunContext) -> None:
+    for epoch in range(config.epochs):
+        loss = 1.0 / (epoch + 1)
+        ctx.log_metric("loss", loss, step=epoch)
+```
+
+```bash
+# サーバー起動（GPUサーバー上で）
+mikon serve
+
+# CLIから起動
+mikon run train --gpu nvidia:0
+
+# 手元PCからはSSHポートフォワードで
+ssh -L 8000:localhost:8000 you@gpu-server
+# → ブラウザで http://localhost:8000
+```
+
+---
+
+## インストール
+
+```bash
+uv add mikon   # 推奨
+pip install mikon
+```
+
+依存ライブラリ（`pynvml`・`psutil`・`watchfiles`・`fastapi` など）は自動でインストールされます。
+
+---
+
+## ドキュメント
+
+詳細な使い方・SDK リファレンス・CLI オプション・API エラーモデルは [USAGE-ja.md](USAGE-ja.md) を参照してください。
+
+---
+
+## ライセンス
+
+MIT

mikon-0.0.1/README.md

@@ -0,0 +1,98 @@
+# mikon
+
+> 日本語版: [README-ja.md](README-ja.md)
+
+A self-hosted tool for managing AI development (training and evaluation jobs) on GPU servers from a browser.
+
+**Write Python the way you normally would, and just add a decorator to your functions.** mikon automatically discovers your jobs, generates config forms, allocates GPUs, launches runs, and displays metrics, logs, and artifacts in real time.
+
+---
+
+## Features
+
+- **Decorator-only discovery** — Just add `@mikon.job`. No registration step, no code changes required.
+- **Auto-generated config UI** — Pydantic fields on `class Config(mikon.Config)` become form widgets automatically (sliders, selects, checkboxes, etc.)
+- **NVIDIA and AMD support** — Specify GPUs in unified `nvidia:0` / `amd:0` format. `CUDA_VISIBLE_DEVICES` / `ROCR_VISIBLE_DEVICES` are set automatically.
+- **Live monitoring** — Metric charts and log streams update every few seconds via SSE.
+- **Artifact management** — Call `ctx.log_artifact()` to make files downloadable from the browser.
+- **Lineage tracking** — `ctx.use_dataset()` / `ctx.use_artifact()` automatically build an upstream/downstream graph.
+- **Module system** — Register swappable components with `@mikon.module`; the UI generates a module-selection form automatically.
+- **Dataset management** — Register existing paths or create datasets with a builder function.
+- **Document viewer** — Markdown, Typst, and TypMark files placed in `docs/` are viewable in the dashboard.
+- **File-based persistence** — No SQL database required. Everything is stored as text files under `.mikon/`.
+- **Independent processes** — Jobs keep running even if the dashboard is restarted.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- GPU server with NVIDIA drivers or AMD ROCm installed
+- `typst` CLI (optional, for Typst document rendering)
+- `typmark-cli` CLI (optional, for TypMark document rendering)
+
+---
+
+## Quick Start
+
+```bash
+# Install
+uv add mikon   # or: pip install mikon
+
+# Initialize project
+mikon init
+```
+
+```python
+# src/train.py
+import mikon
+from mikon import Config, RunContext
+from pydantic import Field
+from typing import Literal
+
+class TrainConfig(Config):
+    lr: float = Field(1e-3, gt=0, le=1)
+    epochs: int = Field(10, ge=1, le=1000)
+    optimizer: Literal["adam", "sgd"] = "adam"
+
+@mikon.job
+def train(config: TrainConfig, ctx: RunContext) -> None:
+    for epoch in range(config.epochs):
+        loss = 1.0 / (epoch + 1)
+        ctx.log_metric("loss", loss, step=epoch)
+```
+
+```bash
+# Start the server on the GPU machine
+mikon serve
+
+# Launch a job from the CLI
+mikon run train --gpu nvidia:0
+
+# Access the dashboard from your local machine via SSH port forwarding
+ssh -L 8000:localhost:8000 you@gpu-server
+# → Open http://localhost:8000 in your browser
+```
+
+---
+
+## Installation
+
+```bash
+uv add mikon   # recommended
+pip install mikon
+```
+
+Dependencies (`pynvml`, `psutil`, `watchfiles`, `fastapi`, etc.) are installed automatically.
+
+---
+
+## Documentation
+
+For the full usage guide, SDK reference, CLI options, and API error model, see [USAGE.md](USAGE.md).
+
+---
+
+## License
+
+MIT

mikon-0.0.1/mikon/__init__.py

@@ -0,0 +1,8 @@
+from mikon.sdk.config import Config
+from mikon.sdk.context import RunContext
+from mikon.sdk import datasets
+from mikon.sdk.datasets import DatasetContext, dataset
+from mikon.sdk.job import job
+from mikon.sdk.module import ModuleFactory, ModuleRef, module
+
+__all__ = ["Config", "DatasetContext", "ModuleFactory", "ModuleRef", "RunContext", "dataset", "datasets", "job", "module"]

mikon-0.0.1/mikon/_runner.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import argparse
+import json
+import signal
+import sys
+import threading
+import time
+import traceback
+from pathlib import Path
+from typing import TextIO
+
+from mikon.sdk.datasets import DatasetContext, get_dataset_registry
+from mikon.sdk.context import RunContext
+from mikon.sdk.job import get_registry
+from mikon.sdk.module import instantiate_config_modules, validate_module_nest_depth
+from mikon.server.discovery import import_project
+from mikon.server.models import RunStatus
+from mikon.server.settings import load_settings
+from mikon.server.store import Store
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--run-dir", required=True)
+    args = parser.parse_args(argv)
+    run_dir = Path(args.run_dir).resolve()
+    store = Store(run_dir.parents[1])
+    meta = store.read_json(run_dir / "meta.json")
+    run_id = meta["run_id"]
+
+    stop_event = threading.Event()
+    heartbeat = threading.Thread(
+        target=_heartbeat_loop, args=(run_dir, stop_event), name="mikon-heartbeat", daemon=True
+    )
+    heartbeat.start()
+
+    def _handle_signal(signum: int, frame: object) -> None:
+        raise KeyboardInterrupt(f"received signal {signum}")
+
+    signal.signal(signal.SIGTERM, _handle_signal)
+    signal.signal(signal.SIGINT, _handle_signal)
+
+    status = RunStatus.completed
+    exit_code = 0
+    error: str | None = None
+    event_logger = _LogEventWriter(run_dir / "logs" / "events.jsonl")
+    original_stdout = sys.stdout
+    original_stderr = sys.stderr
+    sys.stdout = _TeeLineWriter(original_stdout, event_logger, "stdout")
+    sys.stderr = _TeeLineWriter(original_stderr, event_logger, "stderr")
+    try:
+        project_root = Path(meta["project_root"]).resolve()
+        watch_paths = [Path(item).resolve() for item in meta["watch"]]
+        import_project(project_root, watch_paths)
+        kind = meta.get("kind", "job")
+        if kind == "dataset":
+            definition = get_dataset_registry().get(meta["job"])
+        else:
+            definition = get_registry().get(meta["job"])
+        if definition is None:
+            raise RuntimeError(f"{kind} not found during run: {meta['job']}")
+        config_data = store.read_json(run_dir / "config.json")
+        settings = load_settings(project_root)
+        validate_module_nest_depth(config_data, settings.max_module_nest_depth)
+        config = definition.config_type.model_validate(config_data)
+        validate_module_nest_depth(config.model_dump(mode="json"), settings.max_module_nest_depth)
+        instantiate_config_modules(config, max_depth=settings.max_module_nest_depth)
+        ctx = DatasetContext(run_dir, meta["job"]) if kind == "dataset" else RunContext(run_dir)
+        definition.func(config, ctx)
+    except KeyboardInterrupt as exc:
+        status = RunStatus.stopped
+        exit_code = 143
+        error = str(exc)
+    except BaseException:
+        status = RunStatus.failed
+        exit_code = 1
+        error = traceback.format_exc()
+    finally:
+        sys.stdout = original_stdout
+        sys.stderr = original_stderr
+        event_logger.flush()
+        stop_event.set()
+        heartbeat.join(timeout=1)
+        store.write_status(run_id, status, exit_code, error)
+    return exit_code
+
+
+def _heartbeat_loop(run_dir: Path, stop_event: threading.Event) -> None:
+    heartbeat = run_dir / "heartbeat"
+    while not stop_event.is_set():
+        heartbeat.write_text(str(time.time()), encoding="utf-8")
+        stop_event.wait(2)
+
+
+class _LogEventWriter:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        self._seq = 0
+
+    def write_line(self, stream: str, line: str) -> None:
+        with self._lock:
+            record = {"seq": self._seq, "t": time.time(), "stream": stream, "line": line}
+            self._seq += 1
+            with self.path.open("a", encoding="utf-8") as fp:
+                fp.write(json.dumps(record, separators=(",", ":"), allow_nan=False) + "\n")
+                fp.flush()
+
+    def flush(self) -> None:
+        return
+
+
+class _TeeLineWriter:
+    def __init__(self, target: TextIO, event_logger: _LogEventWriter, stream: str) -> None:
+        self.target = target
+        self.event_logger = event_logger
+        self.stream = stream
+        self._buffer = ""
+
+    def write(self, text: str) -> int:
+        written = self.target.write(text)
+        self.target.flush()
+        self._buffer += text
+        while "\n" in self._buffer:
+            line, self._buffer = self._buffer.split("\n", 1)
+            self.event_logger.write_line(self.stream, line)
+        return written
+
+    def flush(self) -> None:
+        self.target.flush()
+        if self._buffer:
+            self.event_logger.write_line(self.stream, self._buffer)
+            self._buffer = ""
+
+    def isatty(self) -> bool:
+        return self.target.isatty()
+
+    @property
+    def encoding(self) -> str | None:
+        return self.target.encoding
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())