shiftgate 0.1.0__py3-none-any.whl

shiftgate/utils/display.py

@@ -0,0 +1,297 @@
+"""
+Rich terminal UI helpers for shiftgate.
+
+All console output in shiftgate goes through this module so that visual style
+is centralised and easy to update.  Each function accepts domain objects
+directly — never raw strings — so the display layer stays decoupled from
+formatting decisions.
+"""
+
+from __future__ import annotations
+
+import time
+
+from rich import box
+from rich.align import Align
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.spinner import Spinner
+from rich.table import Table
+from rich.text import Text
+
+from shiftgate.registry.schemas import AdapterEntry, RoutingTrace, TaskCluster
+
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Colour helpers
+# ---------------------------------------------------------------------------
+
+def _similarity_colour(score: float) -> str:
+    """Return a colour name based on similarity score thresholds."""
+    if score >= 0.80:
+        return "green"
+    if score >= 0.60:
+        return "yellow"
+    return "red"
+
+
+def _similarity_bar(score: float, width: int = 20) -> Text:
+    """Build a coloured progress bar for the similarity score."""
+    filled = round(score * width)
+    bar = "█" * filled + "░" * (width - filled)
+    colour = _similarity_colour(score)
+    text = Text()
+    text.append(bar, style=colour)
+    text.append(f"  {score * 100:.1f}%", style=f"bold {colour}")
+    return text
+
+
+# ---------------------------------------------------------------------------
+# Routing decision panel
+# ---------------------------------------------------------------------------
+
+def show_routing_decision(
+    trace: RoutingTrace,
+    adapter: AdapterEntry | None = None,
+    task_name: str | None = None,
+    backend_name: str | None = None,
+) -> None:
+    """Print a Rich Panel describing a routing decision.
+
+    Parameters
+    ----------
+    trace:
+        The ``RoutingTrace`` returned by the router.
+    adapter:
+        Optional ``AdapterEntry`` for richer adapter display.
+    task_name:
+        Human-readable task cluster name (falls back to trace.matched_task_id).
+    backend_name:
+        Active backend name ('ollama', 'vllm', or None).
+    """
+    colour = _similarity_colour(trace.similarity_score)
+
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="dim", min_width=16)
+    grid.add_column()
+
+    grid.add_row("Query", Text(f'"{trace.query}"', style="italic cyan"))
+
+    task_display = task_name or trace.matched_task_id
+    task_text = Text()
+    task_text.append(task_display, style="bold white")
+    task_text.append("  ")
+    task_text.append_text(_similarity_bar(trace.similarity_score))
+    grid.add_row("Matched Task", task_text)
+
+    if adapter:
+        adapter_text = Text()
+        adapter_text.append(adapter.name, style="bold magenta")
+        adapter_text.append(f"  [{adapter.base_model}]", style="dim")
+        if adapter.hf_repo:
+            adapter_text.append(f"\n  hf: {adapter.hf_repo}", style="dim blue")
+        grid.add_row("Adapter", adapter_text)
+    else:
+        grid.add_row("Adapter", Text(trace.selected_adapter_id, style="bold magenta"))
+
+    backend_text = Text(backend_name or "—", style="green" if backend_name else "dim")
+    grid.add_row("Backend", backend_text)
+
+    if trace.latency_ms is not None:
+        grid.add_row("Latency", Text(f"{trace.latency_ms:.0f} ms", style="dim"))
+
+    panel = Panel(
+        grid,
+        title=f"[bold {colour}] shiftgate routing decision [/bold {colour}]",
+        border_style=colour,
+        expand=False,
+    )
+    console.print()
+    console.print(panel)
+    console.print()
+
+
+# ---------------------------------------------------------------------------
+# Adapter table
+# ---------------------------------------------------------------------------
+
+def show_adapter_table(adapters: list[AdapterEntry]) -> None:
+    """Print a Rich table listing all registered adapters."""
+    if not adapters:
+        console.print("[dim]No adapters registered. Add one with `shiftgate adapter add <hf_repo>`.[/dim]")
+        return
+
+    table = Table(
+        title="Registered Adapters",
+        box=box.ROUNDED,
+        show_header=True,
+        header_style="bold cyan",
+        border_style="cyan",
+    )
+    table.add_column("ID", style="bold magenta", no_wrap=True)
+    table.add_column("Name")
+    table.add_column("Base Model", style="dim")
+    table.add_column("Tags", style="green")
+    table.add_column("HF Repo / Local Path", style="blue")
+    table.add_column("Score", justify="right")
+
+    for a in adapters:
+        location = a.hf_repo or a.local_path or "—"
+        score = f"{a.benchmark_score:.2f}" if a.benchmark_score is not None else "—"
+        tags = ", ".join(a.task_tags) if a.task_tags else "—"
+        table.add_row(a.id, a.name, a.base_model, tags, location, score)
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# Task cluster table
+# ---------------------------------------------------------------------------
+
+def show_task_table(tasks: list[TaskCluster]) -> None:
+    """Print a Rich table listing all task clusters and their preferred adapters."""
+    if not tasks:
+        console.print("[dim]No task clusters found.[/dim]")
+        return
+
+    table = Table(
+        title="Task Clusters",
+        box=box.ROUNDED,
+        show_header=True,
+        header_style="bold cyan",
+        border_style="cyan",
+    )
+    table.add_column("ID", style="bold yellow", no_wrap=True)
+    table.add_column("Name")
+    table.add_column("Description", max_width=40)
+    table.add_column("Preferred Adapters", style="magenta")
+    table.add_column("Centroid", justify="center")
+
+    for t in tasks:
+        preferred = ", ".join(t.preferred_adapters) if t.preferred_adapters else "—"
+        has_centroid = "[green]✓[/green]" if t.embedding_centroid else "[red]✗[/red]"
+        table.add_row(t.id, t.name, t.description, preferred, has_centroid)
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# Adapter swap animation
+# ---------------------------------------------------------------------------
+
+def animate_swap(from_adapter: str, to_adapter: str, duration: float = 1.5) -> None:
+    """Show a short spinner animation while "swapping" from one adapter to another."""
+    spinner = Spinner("dots", style="cyan")
+    label = Text()
+    label.append("Swapping  ", style="dim")
+    label.append(from_adapter, style="bold yellow")
+    label.append("  →  ", style="dim")
+    label.append(to_adapter, style="bold green")
+
+    with Live(Align.center(label), refresh_per_second=12, console=console) as live:
+        end = time.monotonic() + duration
+        while time.monotonic() < end:
+            frame = spinner.render(time.monotonic())
+            display = Text.assemble(frame, "  ", label)
+            live.update(Align.center(display))
+            time.sleep(0.08)
+
+    console.print(
+        f"  [green]✓[/green]  Swapped [yellow]{from_adapter}[/yellow] → [green]{to_adapter}[/green]"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Welcome / init banner
+# ---------------------------------------------------------------------------
+
+def show_welcome_banner() -> None:
+    """Print the shiftgate welcome banner shown during `shiftgate init`."""
+    banner = Text(justify="center")
+    banner.append("\n  ⚡ shiftgate  ", style="bold cyan")
+    banner.append("v0.1\n", style="dim")
+    banner.append("  Intelligent LoRA routing for local LLM inference\n", style="italic white")
+    banner.append("  Inspired by LORAUTER · EPFL 2026\n\n", style="dim")
+
+    panel = Panel(
+        Align.center(banner),
+        border_style="cyan",
+        expand=False,
+    )
+    console.print(Align.center(panel))
+
+
+# ---------------------------------------------------------------------------
+# Adapter acceptance / feedback stats table
+# ---------------------------------------------------------------------------
+
+def show_feedback_stats(scores: dict[str, float], stats: dict[str, int]) -> None:
+    """Print a summary of adapter acceptance rates and overall trace stats.
+
+    Parameters
+    ----------
+    scores:
+        Output of ``feedback.loop.compute_adapter_scores()``.
+    stats:
+        Output of ``feedback.loop.get_trace_stats()``.
+    """
+    console.print()
+    console.print(
+        f"[bold]Traces:[/bold]  "
+        f"total=[cyan]{stats.get('total', 0)}[/cyan]  "
+        f"accepted=[green]{stats.get('accepted', 0)}[/green]  "
+        f"rejected=[red]{stats.get('rejected', 0)}[/red]  "
+        f"unrated=[dim]{stats.get('unrated', 0)}[/dim]"
+    )
+    console.print()
+
+    if not scores:
+        console.print("[dim]No rated traces yet. Run `shiftgate feedback accept/reject` after routing.[/dim]")
+        return
+
+    table = Table(
+        title="Adapter Acceptance Rates",
+        box=box.ROUNDED,
+        header_style="bold cyan",
+        border_style="cyan",
+    )
+    table.add_column("Adapter ID", style="bold magenta")
+    table.add_column("Acceptance Rate", justify="right")
+    table.add_column("Bar")
+
+    for adapter_id, rate in sorted(scores.items(), key=lambda x: -x[1]):
+        rate_text = f"{rate * 100:.1f}%"
+        bar = _similarity_bar(rate, width=15)
+        table.add_row(adapter_id, rate_text, bar)
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# Status display
+# ---------------------------------------------------------------------------
+
+def show_status(
+    backend_name: str | None,
+    n_adapters: int,
+    n_tasks: int,
+    embeddings_ready: bool,
+) -> None:
+    """Print a compact status summary for `shiftgate status`."""
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="dim", min_width=20)
+    grid.add_column()
+
+    backend_style = "green" if backend_name else "red"
+    backend_label = backend_name or "none detected"
+    grid.add_row("Backend", Text(backend_label, style=f"bold {backend_style}"))
+    grid.add_row("Adapters registered", Text(str(n_adapters), style="bold cyan"))
+    grid.add_row("Task clusters", Text(str(n_tasks), style="bold cyan"))
+    emb_style = "green" if embeddings_ready else "yellow"
+    emb_label = "ready" if embeddings_ready else "not initialised — run `shiftgate init`"
+    grid.add_row("Embeddings", Text(emb_label, style=emb_style))
+
+    console.print(Panel(grid, title="shiftgate status", border_style="cyan", expand=False))

shiftgate-0.1.0.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: shiftgate
+Version: 0.1.0
+Summary: Intelligent routing layer that automatically selects the right LoRA adapter for each task in your local agent loop.
+Project-URL: Homepage, https://github.com/shiftgate-ai/shiftgate
+Project-URL: Repository, https://github.com/shiftgate-ai/shiftgate
+Project-URL: Issues, https://github.com/shiftgate-ai/shiftgate/issues
+Author: shiftgate contributors
+License: MIT
+Keywords: adapters,inference,llm,lora,ollama,routing,vllm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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: fastembed>=0.3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: huggingface-hub>=0.22.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: scikit-learn>=1.4.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# shiftgate ⚡
+
+> **shiftgate is an intelligent routing layer that automatically selects the right LoRA adapter for each task in your local agent loop.**
+
+Instead of hardcoding which adapter to use, shiftgate embeds your query and matches it against a catalog of task clusters using cosine similarity — then routes inference to the best-fit LoRA adapter on your running Ollama or vLLM instance. Think of it as "npm for LoRA adapters + an automatic brain that picks the right one per task."
+
+Inspired by the [LORAUTER paper](https://arxiv.org/abs/2406.08213) (EPFL, 2026).
+
+---
+
+## Quickstart
+
+```bash
+# 1. Install (requires Python 3.10+, uv recommended)
+uv add shiftgate
+
+# 2. Initialise: sets up ~/.shiftgate/, downloads the embedding model,
+#    and computes task centroids
+shiftgate init
+
+# 3. Register a LoRA adapter from HuggingFace
+shiftgate adapter add monology/pmc-llama-13b-lora --base meta-llama/Meta-Llama-3-8B --tags medical qa
+
+# 4. Route a query (shows decision, no inference needed)
+shiftgate route "explain the mechanism of action of ibuprofen"
+
+# 5. Route + run (requires Ollama or vLLM running locally)
+shiftgate run "explain the mechanism of action of ibuprofen"
+```
+
+---
+
+## Architecture
+
+```
+User query
+    │
+    ▼
+┌──────────────────────────────────────────────────┐
+│                   shiftgate CLI                  │
+│  shiftgate route / shiftgate run                 │
+└────────────────────┬─────────────────────────────┘
+                     │
+                     ▼
+┌──────────────────────────────────────────────────┐
+│                    Router                        │
+│                                                  │
+│  1. Embed query  (fastembed BAAI/bge-small-en)   │
+│  2. Cosine similarity vs task centroids          │
+│  3. top-K tasks → walk preferred_adapters list   │
+│  4. Return RoutingTrace                          │
+└──────────┬───────────────────────┬───────────────┘
+           │                       │
+           ▼                       ▼
+┌─────────────────┐   ┌────────────────────────────┐
+│  Task Registry  │   │     Adapter Registry        │
+│  ~/.shiftgate/  │   │  ~/.shiftgate/adapters.json │
+│  tasks.json     │   │                            │
+│  (10 defaults)  │   │  Add via:                  │
+└─────────────────┘   │  shiftgate adapter add     │
+                      └────────────┬───────────────┘
+                                   │
+                                   ▼
+              ┌────────────────────────────────┐
+              │        BackendRouter           │
+              │                                │
+              │  Ollama  (localhost:11434)      │
+              │  vLLM    (localhost:8000)       │
+              │  Auto-detected at runtime      │
+              └────────────────────────────────┘
+                                   │
+                                   ▼
+              ┌────────────────────────────────┐
+              │       Feedback Loop            │
+              │  ~/.shiftgate/traces.jsonl     │
+              │  shiftgate feedback accept     │
+              │  shiftgate feedback stats      │
+              └────────────────────────────────┘
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `shiftgate init` | First-time setup: copy defaults to `~/.shiftgate/`, compute embeddings |
+| `shiftgate route "<query>"` | Route a query and show the decision — no inference |
+| `shiftgate run "<query>"` | Route + run via Ollama or vLLM |
+| `shiftgate adapter add <hf_repo>` | Register a new LoRA adapter |
+| `shiftgate adapter list` | Table of all registered adapters |
+| `shiftgate adapter remove <id>` | Remove an adapter |
+| `shiftgate task list` | Table of all task clusters |
+| `shiftgate task add` | Interactively add a new task cluster |
+| `shiftgate feedback accept` | Mark last routing as good |
+| `shiftgate feedback reject` | Mark last routing as bad |
+| `shiftgate feedback stats` | Adapter acceptance rate table |
+| `shiftgate status` | Backend connectivity + registry summary |
+| `shiftgate demo` | Animated demo with fake routing traces |
+
+---
+
+## Using with Ollama
+
+Ollama supports LoRA adapters via custom Modelfiles. Create one per adapter:
+
+```dockerfile
+# my-lora.Modelfile
+FROM llama3
+ADAPTER /path/to/my-adapter.safetensors
+```
+
+```bash
+ollama create my-lora-model -f my-lora.Modelfile
+ollama serve
+```
+
+Register the adapter in shiftgate using the same ID:
+
+```bash
+shiftgate adapter add my-org/my-lora --base meta-llama/Meta-Llama-3-8B
+# The adapter id defaults to the repo slug: "my-lora"
+# shiftgate will pass model="my-lora" to Ollama → activates the Modelfile
+```
+
+## Using with vLLM
+
+vLLM loads LoRA adapters at startup via `--lora-modules`:
+
+```bash
+python -m vllm.entrypoints.openai.api_server \
+    --model meta-llama/Meta-Llama-3-8B \
+    --enable-lora \
+    --lora-modules my-lora=/path/to/adapter
+```
+
+shiftgate sends `"model": "<adapter_id>"` in each `/v1/chat/completions` request, which vLLM maps to the named LoRA module.
+
+---
+
+## How to contribute adapters
+
+1. Fork this repo.
+2. Add an entry to `data/default_adapters.json` (optional — the registry ships empty by design; adapters are user-managed).
+3. Or, better: publish your adapter to HuggingFace and open a PR that documents it in the README's "Community Adapters" section.
+
+To add a task cluster that better matches your domain, edit `data/default_tasks.json` and add `validation_examples` that represent real queries your users ask. Run `shiftgate init` to recompute centroids.
+
+---
+
+## `~/.shiftgate/` layout
+
+```
+~/.shiftgate/
+├── adapters.json          # your registered adapters
+├── tasks.json             # task clusters (copied from defaults on first init)
+├── traces.jsonl           # append-only routing trace log
+└── embeddings_cache.npy   # cached centroids — delete to force re-embedding
+```
+
+---
+
+## Roadmap
+
+| Version | Focus |
+|---|---|
+| **v0.1** | Single base model, multi-adapter routing ← _current_ |
+| v0.2 | Feedback loop + adapter scoring (auto-demote bad adapters) |
+| v0.3 | Multi-model routing (route to different base models per task) |
+| v1.0 | Community registry + web UI |
+
+---
+
+## Development
+
+```bash
+# Clone and install in editable mode with all dev dependencies
+git clone https://github.com/shiftgate-ai/shiftgate
+cd shiftgate
+uv sync --extra dev   # creates .venv, installs shiftgate + dev deps
+
+# Run tests (no GPU needed — tests use synthetic embeddings)
+uv run pytest
+
+# Run the demo inside the venv
+uv run shiftgate demo
+```
+
+> **Note:** `uv sync` reads `pyproject.toml` and resolves a locked environment.  
+> There is no need to run `pip install` manually. Activate the venv with  
+> `.venv/Scripts/activate` (Windows) or `source .venv/bin/activate` (macOS/Linux)  
+> if you want the `shiftgate` command on your `PATH` without the `uv run` prefix.
+
+## Releases and Publishing
+
+Releases are managed through a CI release workflow (e.g. GitHub Actions).  
+**No manual PyPI API token management is required for normal releases.**
+
+The recommended flow:
+
+1. Bump the version in `pyproject.toml` (`version = "x.y.z"`).
+2. Open a PR, get it reviewed and merged.
+3. Tag the commit: `git tag vx.y.z && git push origin vx.y.z`.
+4. The CI workflow builds the wheel with `uv build` and publishes to PyPI  
+   using [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/)  
+   — no stored API token needed.
+
+For a one-off manual publish (maintainers only):
+
+```bash
+uv build                    # produces dist/shiftgate-x.y.z-py3-none-any.whl
+uv publish                  # authenticates via OIDC or a scoped PyPI token
+```
+
+### Project layout
+
+```
+shiftgate/
+├── cli.py               # Typer CLI — all user commands
+├── registry/
+│   ├── schemas.py       # Pydantic models: AdapterEntry, TaskCluster, RoutingTrace
+│   ├── adapter_registry.py
+│   └── task_registry.py
+├── router/
+│   ├── embedder.py      # fastembed wrapper (CPU, singleton)
+│   ├── matcher.py       # cosine similarity, top-K, adapter selection
+│   └── router.py        # orchestrates embed → match → trace
+├── runtime/
+│   └── backend.py       # OllamaBackend, VLLMBackend, BackendRouter
+├── feedback/
+│   └── loop.py          # trace persistence, accept/reject, scoring
+└── utils/
+    └── display.py       # Rich panels, tables, animations
+```
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

shiftgate-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+shiftgate/__init__.py,sha256=5xnE4JLAwev8YWPIggAntTpxOtGCS5f8qDk0kFjTSXw,268
+shiftgate/cli.py,sha256=T_l2Rjw1dQVhzKvTIMK_CMjkGDMiJw53RgLKpCOBBXA,18233
+shiftgate/feedback/__init__.py,sha256=D4rQVHGwfVq_2v6dt0NyNeKhx9zr1izEI_4oW5wnh2c,68
+shiftgate/feedback/loop.py,sha256=HjXztY_pFkb6QH_APseScLKS1srr9QcyE5d-WyiBEPA,5709
+shiftgate/registry/__init__.py,sha256=liGxMtJl6S85eBzfNeE0h7BbC2Eg8iwkzIw2xZEaPkM,82
+shiftgate/registry/adapter_registry.py,sha256=ek9wxp8X5cA4a3fPC_tlm4cco3C9of-oDpEoMowwqOU,6292
+shiftgate/registry/schemas.py,sha256=xZvvwwopC4d3FhuWdJ8pu3lAcwDdZI6ogIWQHNm8L8o,4663
+shiftgate/registry/task_registry.py,sha256=DmwDO5oxjlxnc6w7caZSRCb6Ol1NZn6JHsHOdfitsxs,7407
+shiftgate/router/__init__.py,sha256=Sx6lX51jO8wWGbquYtwdI6Z8N5XCRZyOndr6lqPXVjk,73
+shiftgate/router/embedder.py,sha256=8DsII_pv9I1_apWw2Ev_gU2C0t46Vu2RbuGcwgom8Og,3166
+shiftgate/router/matcher.py,sha256=8JPhC2fT_hL5a750jk4qso0JpNoTlmhh3EtuqBInwyU,3834
+shiftgate/router/router.py,sha256=17ibBHHVznxx_GSDI0n5c-G9tseLfEo5mvWF4T4QEFs,2902
+shiftgate/runtime/__init__.py,sha256=i4knQ_ErspGiQyv87wFsOF3t86YZyqk1Aszaq046o78,70
+shiftgate/runtime/backend.py,sha256=w1M7QM3FpzFlk6OVD2wJfaVHu97pM7_z6XjncSV9mi8,9668
+shiftgate/utils/__init__.py,sha256=jtUdmpchbbJrfjFmAmLGSoJeNBecSUWGy6_LtlJQ97U,51
+shiftgate/utils/display.py,sha256=VCo0mxf5dp3LnsiohOJy7mtclbm0A8fG-C2jhDlDVl8,10540
+shiftgate-0.1.0.dist-info/METADATA,sha256=o-R5FXpFmZ8VUW-av1uXVthB1VG7tw0UJsCQOLw61dc,10843
+shiftgate-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+shiftgate-0.1.0.dist-info/entry_points.txt,sha256=TVcngfC2MKsbEBkTJIaJoCe5nk4bdgaAsBi23o8VVZs,48
+shiftgate-0.1.0.dist-info/RECORD,,

shiftgate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

shiftgate-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shiftgate = shiftgate.cli:app