cargai 0.1.0__tar.gz

cargai-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

cargai-0.1.0/LICENSE

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

cargai-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: cargai
+Version: 0.1.0
+Summary: Toolkit CLI pour installer et gérer des outils tiers liés à l'IA (headroom-ai, ...)
+Project-URL: Repository, https://github.com/LionelHARRY/cargai
+Project-URL: Issues, https://github.com/LionelHARRY/cargai/issues
+Author: Lionel Harry
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cli,installer,llm,toolkit
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: rich>=13
+Requires-Dist: tomli>=2; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cargai
+
+Toolkit CLI pour installer et gérer des outils tiers liés à l'IA, à partir d'un catalogue déclaratif.
+
+## Installation
+
+```bash
+# recommandé
+uv tool install cargai          # ou depuis le repo : uv tool install .
+# alternative
+pipx install cargai
+```
+
+## Utilisation
+
+```bash
+cargai list                         # catalogue + statut d'installation
+cargai info headroom                # détails d'un outil
+cargai install headroom             # installe headroom-ai[proxy]
+cargai install headroom -e all      # avec d'autres extras
+cargai install headroom --dry-run   # affiche la commande sans l'exécuter
+cargai install headroom -U          # met à jour
+cargai uninstall headroom
+cargai doctor                       # vérifie uv / pipx / npm / brew
+```
+
+Les outils Python sont installés isolément via `uv tool` (ou `pipx` à défaut), chacun dans son propre environnement.
+
+## Ajouter un outil
+
+Chaque outil est un fichier TOML :
+
+- intégré au package : `src/cargai/catalog/<nom>.toml`
+- perso (sans modifier le package) : `~/.config/cargai/tools/<nom>.toml` — prioritaire sur le catalogue intégré
+
+```toml
+name = "mon-outil"
+description = "Ce que fait l'outil."
+homepage = "https://..."
+
+[install]
+method = "python"        # python | npm | brew
+package = "mon-outil"    # nom du package PyPI / npm / formule brew
+extras = []              # python uniquement
+python = "3.12"          # optionnel, version de Python à utiliser
+binaries = ["mon-outil"] # sert à détecter si l'outil est installé
+
+[post_install]
+message = "Lance : mon-outil --help"
+```
+
+## Développement
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Publication
+
+Le package PyPI et la commande portent le même nom : `cargai`.
+
+```bash
+uv build && uv publish            # ou : python -m build && twine upload dist/*
+```
+
+## Licence
+
+MIT — voir [LICENSE](LICENSE).

cargai-0.1.0/README.md

@@ -0,0 +1,70 @@
+# cargai
+
+Toolkit CLI pour installer et gérer des outils tiers liés à l'IA, à partir d'un catalogue déclaratif.
+
+## Installation
+
+```bash
+# recommandé
+uv tool install cargai          # ou depuis le repo : uv tool install .
+# alternative
+pipx install cargai
+```
+
+## Utilisation
+
+```bash
+cargai list                         # catalogue + statut d'installation
+cargai info headroom                # détails d'un outil
+cargai install headroom             # installe headroom-ai[proxy]
+cargai install headroom -e all      # avec d'autres extras
+cargai install headroom --dry-run   # affiche la commande sans l'exécuter
+cargai install headroom -U          # met à jour
+cargai uninstall headroom
+cargai doctor                       # vérifie uv / pipx / npm / brew
+```
+
+Les outils Python sont installés isolément via `uv tool` (ou `pipx` à défaut), chacun dans son propre environnement.
+
+## Ajouter un outil
+
+Chaque outil est un fichier TOML :
+
+- intégré au package : `src/cargai/catalog/<nom>.toml`
+- perso (sans modifier le package) : `~/.config/cargai/tools/<nom>.toml` — prioritaire sur le catalogue intégré
+
+```toml
+name = "mon-outil"
+description = "Ce que fait l'outil."
+homepage = "https://..."
+
+[install]
+method = "python"        # python | npm | brew
+package = "mon-outil"    # nom du package PyPI / npm / formule brew
+extras = []              # python uniquement
+python = "3.12"          # optionnel, version de Python à utiliser
+binaries = ["mon-outil"] # sert à détecter si l'outil est installé
+
+[post_install]
+message = "Lance : mon-outil --help"
+```
+
+## Développement
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Publication
+
+Le package PyPI et la commande portent le même nom : `cargai`.
+
+```bash
+uv build && uv publish            # ou : python -m build && twine upload dist/*
+```
+
+## Licence
+
+MIT — voir [LICENSE](LICENSE).

cargai-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cargai"
+version = "0.1.0"
+description = "Toolkit CLI pour installer et gérer des outils tiers liés à l'IA (headroom-ai, ...)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Lionel Harry" }]
+keywords = ["ai", "llm", "cli", "installer", "toolkit"]
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+    "tomli>=2; python_version < '3.11'",
+]
+
+[project.urls]
+Repository = "https://github.com/LionelHARRY/cargai"
+Issues = "https://github.com/LionelHARRY/cargai/issues"
+
+[project.scripts]
+cargai = "cargai.cli:app"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cargai"]

cargai-0.1.0/src/cargai/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cargai-0.1.0/src/cargai/__main__.py

@@ -0,0 +1,3 @@
+from cargai.cli import app
+
+app()

cargai-0.1.0/src/cargai/catalog/headroom.toml

@@ -0,0 +1,20 @@
+name = "headroom"
+display_name = "Headroom"
+description = "Couche d'optimisation de contexte pour LLM : compresse les prompts et réduit les coûts de 50 à 90 %."
+homepage = "https://docs.headroomlabs.ai"
+repository = "https://github.com/headroomlabs-ai/headroom"
+tags = ["context", "proxy", "cost"]
+
+[install]
+method = "python"            # python | npm | brew
+package = "headroom-ai"
+extras = ["proxy"]           # extras installés par défaut (surchargeable avec --extras)
+python = "3.12"              # headroom-ai exige Python >= 3.10
+binaries = ["headroom"]
+
+[post_install]
+message = """
+Démarrer le proxy :   headroom proxy --port 8787
+Puis pointer ton client vers http://localhost:8787 (ex. ANTHROPIC_BASE_URL / OPENAI_BASE_URL).
+Docs : https://docs.headroomlabs.ai/docs
+"""

cargai-0.1.0/src/cargai/cli.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import shutil
+from typing import List, Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from cargai import __version__
+from cargai.installers import InstallerError, install_command, is_installed, run, uninstall_command
+from cargai.registry import RegistryError, get_tool, load_catalog, user_catalog_dir
+
+app = typer.Typer(help="cargai — installe et gère des outils tiers liés à l'IA.", no_args_is_help=True)
+console = Console()
+
+
+def _fail(message: str) -> None:
+    console.print(f"[red]✗[/red] {message}")
+    raise typer.Exit(1)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"cargai {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(False, "--version", "-V", callback=_version_callback, is_eager=True),
+) -> None:
+    pass
+
+
+@app.command("list")
+def list_tools() -> None:
+    """Liste les outils disponibles dans le catalogue."""
+    try:
+        catalog = load_catalog()
+    except RegistryError as e:
+        _fail(str(e))
+    table = Table(title="Catalogue cargai")
+    table.add_column("Nom", style="bold cyan")
+    table.add_column("Description")
+    table.add_column("Méthode")
+    table.add_column("Installé", justify="center")
+    for tool in sorted(catalog.values(), key=lambda t: t.name):
+        table.add_row(tool.name, tool.description, tool.method, "✓" if is_installed(tool) else "—")
+    console.print(table)
+
+
+@app.command()
+def info(name: str) -> None:
+    """Affiche le détail d'un outil."""
+    try:
+        tool = get_tool(name)
+    except RegistryError as e:
+        _fail(str(e))
+    lines = [
+        tool.description,
+        "",
+        f"[bold]Package :[/bold]  {tool.package} ({tool.method})",
+        f"[bold]Extras :[/bold]   {', '.join(tool.extras) or '—'}",
+        f"[bold]Binaires :[/bold] {', '.join(tool.binaries) or '—'}",
+        f"[bold]Installé :[/bold] {'oui' if is_installed(tool) else 'non'}",
+    ]
+    if tool.homepage:
+        lines.append(f"[bold]Site :[/bold]     {tool.homepage}")
+    if tool.repository:
+        lines.append(f"[bold]Repo :[/bold]     {tool.repository}")
+    console.print(Panel("\n".join(lines), title=tool.title, expand=False))
+
+
+@app.command()
+def install(
+    names: List[str] = typer.Argument(..., help="Outil(s) à installer"),
+    extras: Optional[str] = typer.Option(
+        None, "--extras", "-e", help="Extras Python séparés par des virgules (remplace ceux par défaut). '' pour aucun."
+    ),
+    upgrade: bool = typer.Option(False, "--upgrade", "-U", help="Réinstalle / met à jour l'outil."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Affiche les commandes sans les exécuter."),
+) -> None:
+    """Installe un ou plusieurs outils."""
+    chosen_extras = None if extras is None else [x.strip() for x in extras.split(",") if x.strip()]
+    for name in names:
+        try:
+            tool = get_tool(name)
+            if is_installed(tool) and not upgrade:
+                console.print(f"[green]✓[/green] {tool.title} est déjà installé (utilise --upgrade pour mettre à jour).")
+                continue
+            cmd = install_command(tool, chosen_extras, upgrade)
+            console.print(f"[bold]→ {tool.title}[/bold] : [dim]{' '.join(cmd)}[/dim]")
+            if dry_run:
+                continue
+            run(cmd)
+        except (RegistryError, InstallerError) as e:
+            _fail(str(e))
+        console.print(f"[green]✓[/green] {tool.title} installé.")
+        if tool.post_install:
+            console.print(Panel(tool.post_install, title="Pour commencer", expand=False))
+
+
+@app.command()
+def uninstall(
+    names: List[str] = typer.Argument(..., help="Outil(s) à désinstaller"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Affiche les commandes sans les exécuter."),
+) -> None:
+    """Désinstalle un ou plusieurs outils."""
+    for name in names:
+        try:
+            tool = get_tool(name)
+            cmd = uninstall_command(tool)
+            console.print(f"[bold]→ {tool.title}[/bold] : [dim]{' '.join(cmd)}[/dim]")
+            if dry_run:
+                continue
+            run(cmd)
+        except (RegistryError, InstallerError) as e:
+            _fail(str(e))
+        console.print(f"[green]✓[/green] {tool.title} désinstallé.")
+
+
+@app.command()
+def doctor() -> None:
+    """Vérifie les prérequis (uv/pipx, npm, brew) et le catalogue."""
+    checks = {
+        "uv": "recommandé pour les outils Python",
+        "pipx": "alternative à uv",
+        "npm": "outils Node.js",
+        "brew": "outils Homebrew",
+    }
+    for binary, purpose in checks.items():
+        found = shutil.which(binary)
+        mark = "[green]✓[/green]" if found else "[yellow]—[/yellow]"
+        console.print(f"{mark} {binary:<5} {found or 'absent'}  [dim]({purpose})[/dim]")
+    try:
+        catalog = load_catalog()
+        console.print(f"[green]✓[/green] catalogue : {len(catalog)} outil(s) chargé(s)")
+    except RegistryError as e:
+        console.print(f"[red]✗[/red] catalogue : {e}")
+    console.print(f"[dim]Outils perso : ajoute des fichiers .toml dans {user_catalog_dir()}[/dim]")

cargai-0.1.0/src/cargai/installers.py

@@ -0,0 +1,80 @@
+"""Backends d'installation : chaque méthode traduit un Tool en commandes shell."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import List, Optional
+
+from cargai.registry import Tool
+
+
+class InstallerError(Exception):
+    pass
+
+
+def _python_spec(tool: Tool, extras: Optional[List[str]]) -> str:
+    chosen = tool.extras if extras is None else extras
+    return f"{tool.package}[{','.join(chosen)}]" if chosen else tool.package
+
+
+def _python_backend() -> str:
+    for backend in ("uv", "pipx"):
+        if shutil.which(backend):
+            return backend
+    raise InstallerError(
+        "Ni 'uv' ni 'pipx' n'est installé. Installe uv : "
+        "curl -LsSf https://astral.sh/uv/install.sh | sh"
+    )
+
+
+def _require(binary: str, hint: str) -> None:
+    if not shutil.which(binary):
+        raise InstallerError(f"'{binary}' est introuvable. {hint}")
+
+
+def install_command(tool: Tool, extras: Optional[List[str]] = None, upgrade: bool = False) -> List[str]:
+    if tool.method == "python":
+        spec = _python_spec(tool, extras)
+        if _python_backend() == "uv":
+            cmd = ["uv", "tool", "install", spec]
+            if tool.python:
+                cmd += ["--python", tool.python]
+            if upgrade:
+                cmd.append("--force")
+            return cmd
+        cmd = ["pipx", "install", spec]
+        if tool.python:
+            cmd += ["--python", f"python{tool.python}"]
+        if upgrade:
+            cmd.append("--force")
+        return cmd
+    if tool.method == "npm":
+        _require("npm", "Installe Node.js : https://nodejs.org")
+        return ["npm", "install", "-g", f"{tool.package}@latest" if upgrade else tool.package]
+    if tool.method == "brew":
+        _require("brew", "Installe Homebrew : https://brew.sh")
+        return ["brew", "upgrade" if upgrade else "install", tool.package]
+    raise InstallerError(f"Méthode inconnue : {tool.method}")
+
+
+def uninstall_command(tool: Tool) -> List[str]:
+    if tool.method == "python":
+        if _python_backend() == "uv":
+            return ["uv", "tool", "uninstall", tool.package]
+        return ["pipx", "uninstall", tool.package]
+    if tool.method == "npm":
+        return ["npm", "uninstall", "-g", tool.package]
+    if tool.method == "brew":
+        return ["brew", "uninstall", tool.package]
+    raise InstallerError(f"Méthode inconnue : {tool.method}")
+
+
+def is_installed(tool: Tool) -> bool:
+    return bool(tool.binaries) and all(shutil.which(b) for b in tool.binaries)
+
+
+def run(cmd: List[str]) -> None:
+    result = subprocess.run(cmd)
+    if result.returncode != 0:
+        raise InstallerError(f"La commande a échoué (code {result.returncode}) : {' '.join(cmd)}")

cargai-0.1.0/src/cargai/registry.py

@@ -0,0 +1,107 @@
+"""Catalogue des outils : chargé depuis les fichiers TOML embarqués et ceux de l'utilisateur."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+BUILTIN_CATALOG = Path(__file__).parent / "catalog"
+SUPPORTED_METHODS = ("python", "npm", "brew")
+
+
+def user_catalog_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config"
+    return Path(base) / "cargai" / "tools"
+
+
+class RegistryError(Exception):
+    pass
+
+
+@dataclass
+class Tool:
+    name: str
+    description: str
+    method: str
+    package: str
+    display_name: str = ""
+    homepage: str = ""
+    repository: str = ""
+    tags: List[str] = field(default_factory=list)
+    extras: List[str] = field(default_factory=list)
+    python: Optional[str] = None
+    binaries: List[str] = field(default_factory=list)
+    post_install: str = ""
+    source: Optional[Path] = None
+
+    @property
+    def title(self) -> str:
+        return self.display_name or self.name
+
+    @classmethod
+    def from_dict(cls, data: dict, source: Optional[Path] = None) -> "Tool":
+        install = data.get("install", {})
+        missing = [k for k in ("name", "description") if k not in data]
+        missing += [f"install.{k}" for k in ("method", "package") if k not in install]
+        if missing:
+            raise RegistryError(f"{source}: champs manquants : {', '.join(missing)}")
+        if install["method"] not in SUPPORTED_METHODS:
+            raise RegistryError(
+                f"{source}: méthode '{install['method']}' non supportée "
+                f"(attendu : {', '.join(SUPPORTED_METHODS)})"
+            )
+        return cls(
+            name=data["name"],
+            description=data["description"],
+            method=install["method"],
+            package=install["package"],
+            display_name=data.get("display_name", ""),
+            homepage=data.get("homepage", ""),
+            repository=data.get("repository", ""),
+            tags=data.get("tags", []),
+            extras=install.get("extras", []),
+            python=install.get("python"),
+            binaries=install.get("binaries", []),
+            post_install=data.get("post_install", {}).get("message", "").strip(),
+            source=source,
+        )
+
+
+def _load_dir(directory: Path) -> Dict[str, Tool]:
+    tools: Dict[str, Tool] = {}
+    if not directory.is_dir():
+        return tools
+    for path in sorted(directory.glob("*.toml")):
+        with path.open("rb") as f:
+            try:
+                data = tomllib.load(f)
+            except tomllib.TOMLDecodeError as e:
+                raise RegistryError(f"{path}: TOML invalide : {e}") from e
+        tool = Tool.from_dict(data, source=path)
+        tools[tool.name] = tool
+    return tools
+
+
+def load_catalog(extra_dirs: Optional[List[Path]] = None) -> Dict[str, Tool]:
+    """Charge le catalogue intégré, puis les définitions utilisateur (qui l'emportent)."""
+    tools = _load_dir(BUILTIN_CATALOG)
+    for directory in [user_catalog_dir(), *(extra_dirs or [])]:
+        tools.update(_load_dir(directory))
+    return tools
+
+
+def get_tool(name: str) -> Tool:
+    catalog = load_catalog()
+    if name not in catalog:
+        raise RegistryError(
+            f"Outil inconnu : '{name}'. Disponibles : {', '.join(sorted(catalog)) or 'aucun'}"
+        )
+    return catalog[name]

cargai-0.1.0/tests/test_registry.py

@@ -0,0 +1,45 @@
+from unittest import mock
+
+import pytest
+
+from cargai.installers import install_command
+from cargai.registry import RegistryError, Tool, load_catalog
+
+
+def test_builtin_catalog_has_headroom():
+    tool = load_catalog()["headroom"]
+    assert tool.package == "headroom-ai"
+    assert tool.method == "python"
+    assert "headroom" in tool.binaries
+
+
+def test_user_catalog_overrides_and_extends(tmp_path):
+    (tmp_path / "foo.toml").write_text(
+        'name = "foo"\ndescription = "d"\n[install]\nmethod = "npm"\npackage = "foo-cli"\n'
+    )
+    catalog = load_catalog(extra_dirs=[tmp_path])
+    assert catalog["foo"].method == "npm"
+    assert "headroom" in catalog
+
+
+def test_missing_fields_rejected():
+    with pytest.raises(RegistryError):
+        Tool.from_dict({"name": "x", "install": {"method": "python"}})
+
+
+def test_unknown_method_rejected():
+    with pytest.raises(RegistryError):
+        Tool.from_dict({"name": "x", "description": "d", "install": {"method": "apt", "package": "x"}})
+
+
+@mock.patch("cargai.installers.shutil.which", side_effect=lambda b: "/bin/uv" if b == "uv" else None)
+def test_uv_command_with_extras(_which):
+    tool = load_catalog()["headroom"]
+    assert install_command(tool) == ["uv", "tool", "install", "headroom-ai[proxy]", "--python", "3.12"]
+    assert install_command(tool, extras=[])[3] == "headroom-ai"
+
+
+@mock.patch("cargai.installers.shutil.which", side_effect=lambda b: "/bin/pipx" if b == "pipx" else None)
+def test_pipx_fallback(_which):
+    tool = load_catalog()["headroom"]
+    assert install_command(tool, extras=["all"]) == ["pipx", "install", "headroom-ai[all]", "--python", "python3.12"]