telos-ml 1.0.0__py3-none-any.whl

telos/__init__.py

@@ -0,0 +1,74 @@
+"""
+télos (τέλος): Discrete Diffusion & Autoregressive Language Modeling Framework.
+"""
+
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+
+try:
+    __version__ = _pkg_version("telos-ml")
+except PackageNotFoundError:
+    try:
+        __version__ = _pkg_version("telos")
+    except PackageNotFoundError:
+        __version__ = "1.0.0"
+
+from . import dataprep
+from . import train
+from . import eval
+from . import bench
+from .training.hardware import HardwareProfile
+
+from .models.config import TelosConfig
+
+# Primary callable aliases
+prepare_dataset = dataprep.prepare_dataset
+run_train = train.train
+evaluate = eval.evaluate
+benchmark = bench.benchmark
+
+_TORCH_IMPORTS = {
+    "TelosTransformer": ".models.transformer",
+    "UnifiedPyTorchTrainer": ".training.trainer_pytorch",
+}
+
+def __getattr__(name: str):
+    if name == "afm":
+        import importlib
+        return importlib.import_module(".afm", __package__)
+    if name == "MLXTelosTransformer":
+        from .models import MLXTelosTransformer
+        return MLXTelosTransformer
+    if name == "UnifiedMLXTrainer":
+        from .training import UnifiedMLXTrainer
+        return UnifiedMLXTrainer
+    if name in _TORCH_IMPORTS:
+        try:
+            import importlib
+            mod = importlib.import_module(_TORCH_IMPORTS[name], __package__)
+            return getattr(mod, name)
+        except ImportError as err:
+            raise ImportError(
+                f"{name} requires 'torch', which is not available in this environment. "
+                "Install it via `pip install torch`."
+            ) from err
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+__all__ = [
+    "__version__",
+    "dataprep",
+    "train",
+    "run_train",
+    "eval",
+    "bench",
+    "prepare_dataset",
+    "evaluate",
+    "benchmark",
+    "afm",
+    "TelosTransformer",
+    "TelosConfig",
+    "MLXTelosTransformer",
+    "UnifiedMLXTrainer",
+    "UnifiedPyTorchTrainer",
+    "HardwareProfile",
+]
+

telos/__main__.py

@@ -0,0 +1,9 @@
+"""
+telos.__main__
+Entry point enabling `python -m telos`.
+"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

telos/afm/__init__.py

@@ -0,0 +1,67 @@
+"""
+telos.afm
+Python access to Apple's on-device Foundation Models.
+
+Usage:
+    >>> import telos.afm
+    >>> telos.afm.probe().describe()
+    >>> telos.afm.generate("Write a haiku about gradients.")
+
+Requires macOS 26+, an Apple Intelligence-eligible Apple Silicon Mac with it
+enabled, and the Xcode Command Line Tools. The Swift bridge is built on first
+use into ~/.cache/telos (override with TELOS_CACHE_DIR).
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+from .availability import (
+    AFMAvailability,
+    AFMUnavailableError,
+    FALLBACK_CHIP_FAMILY,
+    MIN_MACOS_MAJOR,
+    MODEL_CORE,
+    MODEL_CORE_ADVANCED,
+    probe,
+    require,
+)
+from .bridge import AFMBridge, cache_root, ensure_bridge_binary
+
+__all__ = [
+    "AFMAvailability",
+    "AFMBridge",
+    "AFMUnavailableError",
+    "FALLBACK_CHIP_FAMILY",
+    "MIN_MACOS_MAJOR",
+    "MODEL_CORE",
+    "MODEL_CORE_ADVANCED",
+    "cache_root",
+    "ensure_bridge_binary",
+    "generate",
+    "probe",
+    "require",
+]
+
+
+def generate(
+    prompt: str,
+    *,
+    max_new_tokens: int = 256,
+    temperature: float = 0.0,
+    stop: Optional[Sequence[str]] = None,
+    instructions: Optional[str] = None,
+) -> str:
+    """Generates one completion on the on-device model.
+
+    Opens a bridge, generates, and closes it. Hold an AFMBridge open for
+    repeated calls so the process and model stay warm.
+    """
+    with AFMBridge() as bridge:
+        return bridge.generate(
+            prompt,
+            max_new_tokens=max_new_tokens,
+            temperature=temperature,
+            stop=stop,
+            instructions=instructions,
+        )

telos/afm/_swift/afm_bridge.swift

@@ -0,0 +1,136 @@
+import Foundation
+import FoundationModels
+
+struct GenerationRequest: Codable {
+    let id: Int?
+    let prompt: String
+    let instructions: String?
+    let maxTokens: Int?
+    let temperature: Double?
+    let stopTokens: [String]?
+}
+
+struct GenerationResponse: Codable {
+    let id: Int?
+    let content: String
+    let error: String?
+}
+
+/// One-shot availability report, emitted for `afm_bridge --status`.
+///
+/// `FoundationModels` exposes no public selector for a specific on-device
+/// model, only `SystemLanguageModel.default`. The `check` field therefore
+/// reports *why* the default model is or is not usable, and the Python side
+/// maps that onto the Core / Core Advanced preference.
+struct StatusResponse: Codable {
+    let available: Bool
+    /// One of: "available", "device_not_eligible",
+    /// "apple_intelligence_not_enabled", "model_not_ready", "unknown".
+    let check: String
+    let detail: String?
+}
+
+func describeAvailability(_ model: SystemLanguageModel) -> StatusResponse {
+    switch model.availability {
+    case .available:
+        return StatusResponse(available: true, check: "available", detail: nil)
+    case .unavailable(let reason):
+        switch reason {
+        case .deviceNotEligible:
+            return StatusResponse(
+                available: false,
+                check: "device_not_eligible",
+                detail: "This device is not eligible for Apple Intelligence."
+            )
+        case .appleIntelligenceNotEnabled:
+            return StatusResponse(
+                available: false,
+                check: "apple_intelligence_not_enabled",
+                detail: "Apple Intelligence is not enabled in System Settings."
+            )
+        case .modelNotReady:
+            return StatusResponse(
+                available: false,
+                check: "model_not_ready",
+                detail: "The on-device model is still downloading or preparing."
+            )
+        @unknown default:
+            return StatusResponse(available: false, check: "unknown", detail: "\(reason)")
+        }
+    @unknown default:
+        return StatusResponse(available: false, check: "unknown", detail: nil)
+    }
+}
+
+func emitJSON<T: Encodable>(_ value: T) {
+    if let data = try? JSONEncoder().encode(value),
+       let str = String(data: data, encoding: .utf8) {
+        print(str)
+        fflush(stdout)
+    }
+}
+
+@main
+struct AFMBridge {
+    static func main() async {
+        let model = SystemLanguageModel.default
+
+        // One-shot status probe: `afm_bridge --status`. Exits immediately so
+        // the Python side can report availability without opening a session.
+        if CommandLine.arguments.contains("--status") {
+            emitJSON(describeAvailability(model))
+            return
+        }
+
+        guard model.isAvailable else {
+            let resp = GenerationResponse(id: nil, content: "", error: "SystemLanguageModel is not available on this system.")
+            emitJSON(resp)
+            return
+        }
+
+        let stdin = FileHandle.standardInput
+        while let lineData = try? stdin.readLine() {
+            guard !lineData.isEmpty else { continue }
+            guard let req = try? JSONDecoder().decode(GenerationRequest.self, from: lineData) else {
+                continue
+            }
+
+            let instructions = req.instructions ?? "You are an expert programming and reasoning assistant. Provide direct, concise, and accurate output without conversational filler."
+            let session = LanguageModelSession(model: model, instructions: instructions)
+            let options = GenerationOptions(
+                temperature: req.temperature ?? 0.0,
+                maximumResponseTokens: req.maxTokens ?? 256
+            )
+
+            do {
+                let response = try await session.respond(to: req.prompt, options: options)
+                var text = response.content
+                if let stopTokens = req.stopTokens {
+                    for stop in stopTokens {
+                        if let range = text.range(of: stop) {
+                            text = String(text[..<range.lowerBound])
+                        }
+                    }
+                }
+                emitJSON(GenerationResponse(id: req.id, content: text, error: nil))
+            } catch {
+                emitJSON(GenerationResponse(id: req.id, content: "", error: "\(error)"))
+            }
+        }
+    }
+}
+
+extension FileHandle {
+    func readLine() throws -> Data? {
+        var buffer = Data()
+        while true {
+            guard let byteData = try self.read(upToCount: 1), !byteData.isEmpty else {
+                return buffer.isEmpty ? nil : buffer
+            }
+            if byteData[0] == 10 { // newline \n
+                return buffer
+            }
+            buffer.append(byteData)
+        }
+    }
+}

telos/afm/availability.py

@@ -0,0 +1,195 @@
+"""
+AFM Availability
+Detects whether Apple's on-device Foundation Models are usable on this machine.
+
+FoundationModels exposes only `SystemLanguageModel.default`, so this detects
+eligibility and names what is called rather than switching models at runtime.
+"""
+
+from __future__ import annotations
+
+import platform
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Optional
+
+from .bridge import AFMUnavailableError, query_status
+
+__all__ = [
+    "AFMAvailability",
+    "AFMUnavailableError",
+    "MIN_MACOS_MAJOR",
+    "FALLBACK_CHIP_FAMILY",
+    "probe",
+    "require",
+]
+
+MIN_MACOS_MAJOR = 26
+FALLBACK_CHIP_FAMILY = "M3"
+
+MODEL_CORE_ADVANCED = "afm-3-core-advanced"
+MODEL_CORE = "afm-3-core"
+
+
+@dataclass(frozen=True)
+class AFMAvailability:
+    """Outcome of an on-device Foundation Models probe."""
+
+    available: bool
+    #: Name of the model being called, or None when unavailable.
+    model: Optional[str]
+    #: Smaller model offered as fallback on M3+, or None on older silicon.
+    fallback_model: Optional[str]
+    #: "ok" when available, otherwise why not.
+    reason: str
+    macos_version: Optional[tuple[int, ...]]
+    chip_family: Optional[str]
+    framework_check: Optional[str]
+    xcode_clt: bool
+    swiftc: bool
+
+    def describe(self) -> str:
+        """One-line human summary."""
+        if self.available:
+            line = f"{self.model} available (Apple on-device Foundation Models)."
+            if self.fallback_model:
+                line += f" Fallback on this chip: {self.fallback_model}."
+            return line
+        return f"Apple on-device Foundation Models unavailable: {self.reason}"
+
+
+def _parse_macos_major(ver: str) -> Optional[tuple[int, ...]]:
+    parts = []
+    for chunk in ver.split("."):
+        if not chunk.isdigit():
+            break
+        parts.append(int(chunk))
+    return tuple(parts) if parts else None
+
+
+def _chip_family() -> Optional[str]:
+    # sysctl can be blocked by a sandbox; unknown is fine, runtime check decides.
+    try:
+        res = subprocess.run(
+            ["sysctl", "-n", "machdep.cpu.brand_string"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if res.returncode != 0:
+        return None
+    match = re.search(r"\bApple\s+(M\d+)", res.stdout)
+    return match.group(1) if match else None
+
+
+def _chip_at_least(family: Optional[str], minimum: str) -> bool:
+    if family is None:
+        return False
+    m = re.fullmatch(r"M(\d+)", family)
+    n = re.fullmatch(r"M(\d+)", minimum)
+    if not m or not n:
+        return False
+    return int(m.group(1)) >= int(n.group(1))
+
+
+def _has_xcode_clt() -> bool:
+    try:
+        res = subprocess.run(["xcode-select", "-p"], capture_output=True, text=True, timeout=5)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return res.returncode == 0
+
+
+def probe(*, runtime: bool = True) -> AFMAvailability:
+    """Detects whether the on-device models are usable. Never raises for an
+    unsupported machine; inspect `available` and `reason` instead."""
+    if platform.system() != "Darwin":
+        return AFMAvailability(
+            available=False,
+            model=None,
+            fallback_model=None,
+            reason=f"Apple Foundation Models are macOS-only (this is {platform.system()}).",
+            macos_version=None,
+            chip_family=None,
+            framework_check=None,
+            xcode_clt=False,
+            swiftc=False,
+        )
+
+    macos_ver = _parse_macos_major(platform.mac_ver()[0])
+    chip = _chip_family()
+    has_clt = _has_xcode_clt()
+    has_swiftc = shutil.which("swiftc") is not None
+
+    def unavailable(reason: str, framework_check: Optional[str] = None) -> AFMAvailability:
+        return AFMAvailability(
+            available=False,
+            model=None,
+            fallback_model=None,
+            reason=reason,
+            macos_version=macos_ver,
+            chip_family=chip,
+            framework_check=framework_check,
+            xcode_clt=has_clt,
+            swiftc=has_swiftc,
+        )
+
+    if platform.machine() != "arm64":
+        return unavailable(f"Apple Foundation Models require Apple Silicon (this is {platform.machine()}).")
+    if macos_ver is None:
+        return unavailable("Could not determine the macOS version.")
+    if macos_ver[0] < MIN_MACOS_MAJOR:
+        return unavailable(
+            f"Apple Foundation Models require macOS {MIN_MACOS_MAJOR} or later "
+            f"(this is {'.'.join(map(str, macos_ver))})."
+        )
+
+    fallback = MODEL_CORE if _chip_at_least(chip, FALLBACK_CHIP_FAMILY) else None
+
+    if not runtime:
+        # Platform can host the framework; Apple Intelligence state is runtime-only.
+        return AFMAvailability(
+            available=True,
+            model=MODEL_CORE_ADVANCED,
+            fallback_model=fallback,
+            reason="ok",
+            macos_version=macos_ver,
+            chip_family=chip,
+            framework_check=None,
+            xcode_clt=has_clt,
+            swiftc=has_swiftc,
+        )
+
+    try:
+        status = query_status()
+    except AFMUnavailableError as exc:
+        return unavailable(exc.reason)
+
+    check = str(status.get("check", "unknown"))
+    if not status.get("available"):
+        detail = status.get("detail") or None
+        return unavailable(detail or f"The on-device model is unavailable ({check}).", check)
+
+    return AFMAvailability(
+        available=True,
+        model=MODEL_CORE_ADVANCED,
+        fallback_model=fallback,
+        reason="ok",
+        macos_version=macos_ver,
+        chip_family=chip,
+        framework_check=check,
+        xcode_clt=has_clt,
+        swiftc=has_swiftc,
+    )
+
+
+def require(*, runtime: bool = True) -> AFMAvailability:
+    """Like probe(), but raises when the models are unavailable."""
+    avail = probe(runtime=runtime)
+    if not avail.available:
+        raise AFMUnavailableError(avail.reason)
+    return avail