heulistic 0.1.0__tar.gz

heulistic-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Secrets — never commit actual env files
+.env
+.env.local
+*.env.local
+.env.local.example
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+.pytest_cache/
+
+# Node
+node_modules/
+.next/
+out/
+
+# Terraform
+**/.terraform/
+*.tfstate
+*.tfstate.backup
+*.tfvars
+!*.tfvars.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# miscellaneous files
+prd.txt
+config.yaml
+ARCHITECTURE.md
+qwen-config.yaml
+stripe-usage-billing.md
+
+# The scratch copy at the repo root is ignored, but the reference vendored into
+# heulistic-axolotl is the generator's input and must be committed. Without the
+# negation the bare pattern matched it at any depth, so it was silently absent
+# from CI while present locally.
+axolotl.yaml
+!packages/heulistic-axolotl/reference/axolotl.yaml

heulistic-0.1.0/LICENSE

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

heulistic-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: heulistic
+Version: 0.1.0
+Summary: Fine-tune LLMs without the infrastructure
+Project-URL: Homepage, https://heulistic.com
+Project-URL: Documentation, https://heulistic.com/docs
+Author-email: Heulistic <hello@heulistic.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: axolotl,fine-tuning,llm,lora,machine-learning,qlora
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: heulistic-axolotl<0.2.0,>=0.1.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# heulistic
+
+Fine-tune LLMs without the infrastructure.
+
+Run the full Heulistic stack locally on your own hardware — no cloud account, no billing, no setup beyond Docker.
+
+## Installation
+
+```bash
+pip install heulistic
+```
+
+Requires Python 3.10+ and Docker Desktop (or Docker Engine + Compose plugin).
+
+## Quick start
+
+```bash
+pip install heulistic
+
+heulistic init                        # starter config, sized to your GPU
+heulistic validate-config config.yaml # check it — offline, no Docker needed
+heulistic start                       # bring the local stack up
+heulistic train config.yaml           # submit and follow the logs
+heulistic download <job-id>           # collect the trained model
+```
+
+## Training from the terminal
+
+```bash
+heulistic train config.yaml
+heulistic train config.yaml --dataset ./data.jsonl
+heulistic train config.yaml --hf-token hf_...   # gated base models
+heulistic train config.yaml --detach            # submit without following
+heulistic train config.yaml --no-validate       # skip the pre-flight check
+```
+
+The config is validated locally first, so a typo costs nothing. Logs stream
+until the run ends; Ctrl-C detaches without stopping the job. On success you
+are told where to get the model.
+
+```bash
+heulistic download <job-id>              # ./<job-id>-model.tar.gz
+heulistic download <job-id> -o model.tgz
+heulistic download <job-id> --url-only
+```
+
+## Starting from a working config
+
+```bash
+heulistic init                    # writes config.yaml
+heulistic init -m Qwen/Qwen2.5-0.5B
+heulistic init -o experiments/run1.yaml
+```
+
+`init` reads your GPU and picks a base model that fits it, so your first run
+does not OOM twenty minutes in. The generated file passes `validate-config`
+with no findings.
+
+## Checking a config
+
+Validate an Axolotl config before spending a GPU hour on it. Works offline —
+no Docker, no running stack, no account.
+
+```bash
+heulistic validate-config config.yaml
+```
+
+```
+Checking config.yaml
+
+  error   line 3   num_epochs        num_epochs must be greater than 0
+  error   line 5   micro_batch_size  'micro_batch_size' expects int | None, got str
+  warning line 2   lr                Unknown field 'lr' — did you mean 'learning_rate'?
+  info             bf16              'bf16' is not set — it defaults to 'auto'
+
+  2 errors, 1 warning, 1 suggestion
+```
+
+Field names, types, defaults and required-ness come from Axolotl's own
+[config reference](https://docs.axolotl.ai/docs/config-reference.html), so the
+checks track upstream rather than a hand-written list.
+
+```bash
+# Check it also fits your GPU
+heulistic validate-config config.yaml --gpu
+
+# ...or a card you don't have in front of you
+heulistic validate-config config.yaml --vram 24
+heulistic validate-config config.yaml --vram 88 --gpus 4
+
+# Fail on warnings too, for CI
+heulistic validate-config config.yaml --strict
+
+# Errors only, or JSON for tooling
+heulistic validate-config config.yaml --quiet
+heulistic validate-config config.yaml --json
+```
+
+Exit codes: `0` clean, `1` problems found, `2` bad invocation.
+
+## Running the local stack
+
+```bash
+# Start the stack (opens your browser automatically)
+heulistic start
+
+# GPU-less mode (CPU only — training will be slow)
+heulistic start --no-gpu
+
+# Use a HuggingFace token for gated models
+heulistic start --hf-token hf_...
+
+# Custom ports
+heulistic start --port 3001 --api-port 8001
+
+# What's running, and what are my jobs doing?
+heulistic status
+
+# View logs
+heulistic logs
+heulistic logs -f   # follow
+
+# Stop
+heulistic stop
+```
+
+`heulistic status` exits `0` only when every service is up, so it can gate a
+script:
+
+```
+Heulistic local stack
+
+  db          running (healthy)
+  minio       running
+  api         running             http://localhost:8000
+  scheduler   running
+  frontend    running             http://localhost:3000
+
+  Jobs: 1 completed, 2 running
+```
+
+## Managed Cloud
+
+Need more GPU or don't want to manage infrastructure? [Heulistic Cloud](https://heulistic.com) handles provisioning, scaling, and cost — pay only for what you use.

heulistic-0.1.0/README.md

@@ -0,0 +1,144 @@
+# heulistic
+
+Fine-tune LLMs without the infrastructure.
+
+Run the full Heulistic stack locally on your own hardware — no cloud account, no billing, no setup beyond Docker.
+
+## Installation
+
+```bash
+pip install heulistic
+```
+
+Requires Python 3.10+ and Docker Desktop (or Docker Engine + Compose plugin).
+
+## Quick start
+
+```bash
+pip install heulistic
+
+heulistic init                        # starter config, sized to your GPU
+heulistic validate-config config.yaml # check it — offline, no Docker needed
+heulistic start                       # bring the local stack up
+heulistic train config.yaml           # submit and follow the logs
+heulistic download <job-id>           # collect the trained model
+```
+
+## Training from the terminal
+
+```bash
+heulistic train config.yaml
+heulistic train config.yaml --dataset ./data.jsonl
+heulistic train config.yaml --hf-token hf_...   # gated base models
+heulistic train config.yaml --detach            # submit without following
+heulistic train config.yaml --no-validate       # skip the pre-flight check
+```
+
+The config is validated locally first, so a typo costs nothing. Logs stream
+until the run ends; Ctrl-C detaches without stopping the job. On success you
+are told where to get the model.
+
+```bash
+heulistic download <job-id>              # ./<job-id>-model.tar.gz
+heulistic download <job-id> -o model.tgz
+heulistic download <job-id> --url-only
+```
+
+## Starting from a working config
+
+```bash
+heulistic init                    # writes config.yaml
+heulistic init -m Qwen/Qwen2.5-0.5B
+heulistic init -o experiments/run1.yaml
+```
+
+`init` reads your GPU and picks a base model that fits it, so your first run
+does not OOM twenty minutes in. The generated file passes `validate-config`
+with no findings.
+
+## Checking a config
+
+Validate an Axolotl config before spending a GPU hour on it. Works offline —
+no Docker, no running stack, no account.
+
+```bash
+heulistic validate-config config.yaml
+```
+
+```
+Checking config.yaml
+
+  error   line 3   num_epochs        num_epochs must be greater than 0
+  error   line 5   micro_batch_size  'micro_batch_size' expects int | None, got str
+  warning line 2   lr                Unknown field 'lr' — did you mean 'learning_rate'?
+  info             bf16              'bf16' is not set — it defaults to 'auto'
+
+  2 errors, 1 warning, 1 suggestion
+```
+
+Field names, types, defaults and required-ness come from Axolotl's own
+[config reference](https://docs.axolotl.ai/docs/config-reference.html), so the
+checks track upstream rather than a hand-written list.
+
+```bash
+# Check it also fits your GPU
+heulistic validate-config config.yaml --gpu
+
+# ...or a card you don't have in front of you
+heulistic validate-config config.yaml --vram 24
+heulistic validate-config config.yaml --vram 88 --gpus 4
+
+# Fail on warnings too, for CI
+heulistic validate-config config.yaml --strict
+
+# Errors only, or JSON for tooling
+heulistic validate-config config.yaml --quiet
+heulistic validate-config config.yaml --json
+```
+
+Exit codes: `0` clean, `1` problems found, `2` bad invocation.
+
+## Running the local stack
+
+```bash
+# Start the stack (opens your browser automatically)
+heulistic start
+
+# GPU-less mode (CPU only — training will be slow)
+heulistic start --no-gpu
+
+# Use a HuggingFace token for gated models
+heulistic start --hf-token hf_...
+
+# Custom ports
+heulistic start --port 3001 --api-port 8001
+
+# What's running, and what are my jobs doing?
+heulistic status
+
+# View logs
+heulistic logs
+heulistic logs -f   # follow
+
+# Stop
+heulistic stop
+```
+
+`heulistic status` exits `0` only when every service is up, so it can gate a
+script:
+
+```
+Heulistic local stack
+
+  db          running (healthy)
+  minio       running
+  api         running             http://localhost:8000
+  scheduler   running
+  frontend    running             http://localhost:3000
+
+  Jobs: 1 completed, 2 running
+```
+
+## Managed Cloud
+
+Need more GPU or don't want to manage infrastructure? [Heulistic Cloud](https://heulistic.com) handles provisioning, scaling, and cost — pay only for what you use.

heulistic-0.1.0/heulistic/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point for `python -m heulistic`.
+
+The `heulistic` console script is the normal way in; this makes the module form
+work too, which is how the CLI gets run inside a virtualenv that has not been
+activated.
+"""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

heulistic-0.1.0/heulistic/client.py

@@ -0,0 +1,161 @@
+"""Talk to the local Heulistic API.
+
+Standard library only, so `pip install heulistic` stays light — which is why
+multipart bodies are assembled here rather than handed to a library.
+
+Local mode accepts a fixed bearer token in place of a Cognito JWT. When cloud
+support lands this is the seam where a real credential goes.
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import secrets
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Iterator
+
+__all__ = [
+    "ApiError",
+    "encode_multipart",
+    "submit",
+    "get_job",
+    "download_url",
+    "stream_logs",
+]
+
+DEV_TOKEN = "dev-localuser"
+_TIMEOUT = 30
+# Training runs are long; the log stream must not time out mid-job.
+_STREAM_TIMEOUT = 60 * 60 * 24
+
+
+class ApiError(Exception):
+    """The API refused the request, carrying its `detail` where there is one."""
+
+
+def _headers(content_type: str | None = None) -> dict[str, str]:
+    headers = {"Authorization": f"Bearer {DEV_TOKEN}"}
+    if content_type:
+        headers["Content-Type"] = content_type
+    return headers
+
+
+def _raise_for_error(exc: urllib.error.HTTPError) -> None:
+    try:
+        detail = json.loads(exc.read()).get("detail", "")
+    except Exception:
+        detail = ""
+    raise ApiError(detail or f"HTTP {exc.code}") from exc
+
+
+def _request(
+    method: str,
+    url: str,
+    *,
+    body: bytes | None = None,
+    content_type: str | None = None,
+    stream: bool = False,
+):
+    """Perform one HTTP request. Tests replace this wholesale."""
+    request = urllib.request.Request(
+        url, data=body, method=method, headers=_headers(content_type)
+    )
+    try:
+        response = urllib.request.urlopen(
+            request, timeout=_STREAM_TIMEOUT if stream else _TIMEOUT
+        )
+    except urllib.error.HTTPError as exc:
+        _raise_for_error(exc)
+    except urllib.error.URLError as exc:
+        raise ApiError(
+            f"Could not reach the Heulistic API at {url} — is it running? "
+            "Start it with: heulistic start"
+        ) from exc
+    return response if stream else response.read()
+
+
+def encode_multipart(
+    fields: dict[str, str | None], files: dict[str, tuple[str, bytes]]
+) -> tuple[str, bytes]:
+    """Build a multipart/form-data body. Returns (content_type, body)."""
+    boundary = secrets.token_hex(16)
+    parts: list[bytes] = []
+
+    for name, value in fields.items():
+        if value in (None, ""):
+            continue  # an empty optional field must not be sent at all
+        parts.append(
+            f"--{boundary}\r\n"
+            f'Content-Disposition: form-data; name="{name}"\r\n\r\n'
+            f"{value}\r\n".encode()
+        )
+
+    for name, (filename, content) in files.items():
+        mime = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+        parts.append(
+            f"--{boundary}\r\n"
+            f'Content-Disposition: form-data; name="{name}"; filename="{filename}"\r\n'
+            f"Content-Type: {mime}\r\n\r\n".encode()
+        )
+        parts.append(content)
+        parts.append(b"\r\n")
+
+    parts.append(f"--{boundary}--\r\n".encode())
+    return f"multipart/form-data; boundary={boundary}", b"".join(parts)
+
+
+def submit(
+    api_url: str,
+    config: Path,
+    dataset: Path | None = None,
+    hf_token: str | None = None,
+) -> dict:
+    """Submit a training job. Returns the API's job record."""
+    files = {"config": (config.name, config.read_bytes())}
+    if dataset is not None:
+        files["dataset"] = (dataset.name, dataset.read_bytes())
+
+    content_type, body = encode_multipart({"hf_token": hf_token}, files)
+    raw = _request(
+        "POST", f"{api_url}/api/jobs", body=body, content_type=content_type
+    )
+    return json.loads(raw)
+
+
+def get_job(api_url: str, job_id: str) -> dict:
+    return json.loads(_request("GET", f"{api_url}/api/jobs/{job_id}"))
+
+
+def download_url(api_url: str, job_id: str) -> str:
+    raw = _request("GET", f"{api_url}/api/jobs/{job_id}/download")
+    return json.loads(raw)["url"]
+
+
+def _stream_lines(url: str) -> Iterator[bytes]:
+    response = _request("GET", url, stream=True)
+    for raw_line in response:
+        yield raw_line.rstrip(b"\n")
+
+
+def stream_logs(api_url: str, job_id: str) -> Iterator[tuple[str, str]]:
+    """Yield ("line", text) for each log line, then ("done", status) at the end.
+
+    Server-sent events; anything that is not a well-formed `data:` frame — a
+    keepalive, a blank separator — is skipped rather than surfaced.
+    """
+    url = f"{api_url}/api/jobs/{job_id}/logs"
+    for raw_line in _stream_lines(url):
+        if not raw_line.startswith(b"data: "):
+            continue
+        try:
+            payload = json.loads(raw_line[len(b"data: "):])
+        except json.JSONDecodeError:
+            continue
+        if payload.get("event") == "done":
+            yield "done", payload.get("status", "")
+            return
+        if "line" in payload:
+            yield "line", payload["line"]

heulistic-0.1.0/heulistic/download_cmd.py

@@ -0,0 +1,92 @@
+"""`heulistic download` — fetch a finished model.
+
+Locally the artifact sits in MinIO inside Docker, so without this the output of
+a run is hard to reach. The API hands back a URL; this follows it.
+"""
+
+from __future__ import annotations
+
+import shutil
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from . import client, stack
+
+_SUFFIX = "-model.tar.gz"
+
+
+def _fetch(url: str, dest: Path) -> Path:
+    """Stream the artifact to disk. Replaced in tests."""
+    with urllib.request.urlopen(url, timeout=300) as response, open(dest, "wb") as out:
+        shutil.copyfileobj(response, out)
+    return dest
+
+
+def _resolve_destination(output: Optional[Path], job_id: str) -> Path:
+    default_name = f"{job_id}{_SUFFIX}"
+    if output is None:
+        return Path.cwd() / default_name
+    if output.is_dir():
+        return output / default_name
+    return output
+
+
+def download(
+    job_id: str = typer.Argument(..., help="Job ID to download the model for."),
+    output: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="File or directory to write to."
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite an existing file."),
+    url_only: bool = typer.Option(
+        False, "--url-only", help="Print the download URL instead of fetching it."
+    ),
+) -> None:
+    """Download the trained model for a completed job."""
+    api_url = stack.api_url()
+    if not api_url:
+        typer.secho("Heulistic is not running.", fg=typer.colors.RED)
+        typer.echo("Start it with: heulistic start")
+        raise typer.Exit(code=1)
+
+    try:
+        job = client.get_job(api_url, job_id)
+    except client.ApiError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+    status = job.get("status", "unknown")
+    if status != "completed":
+        typer.secho(f"Job {job_id} is '{status}' — a model is only available once "
+                    "the job has completed.", fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+    try:
+        url = client.download_url(api_url, job_id)
+    except client.ApiError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+    if url_only:
+        typer.echo(url)
+        raise typer.Exit(code=0)
+
+    dest = _resolve_destination(output, job_id)
+    if dest.exists() and not force:
+        typer.secho(f"{dest} already exists — pass --force to overwrite.",
+                    fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+    typer.echo(f"Downloading {job_id} → {dest}")
+    try:
+        _fetch(url, dest)
+    except (urllib.error.URLError, OSError) as exc:
+        typer.secho(f"Download failed: {exc}", fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+    size_mb = dest.stat().st_size / (1024 * 1024)
+    typer.secho(f"Saved {dest} ({size_mb:.1f} MB)", fg=typer.colors.GREEN)
+    typer.echo(f"  tar xzf {dest.name}")