Metadata-Version: 2.4
Name: tamebi
Version: 1.1.3
Summary: Detect hardware and estimate LLM model inference capability
Author-email: Tamebi <contact@tamebi.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://tamebi.ai
Project-URL: Repository, https://github.com/tamebi-ai/tamebifoundrypackage
Keywords: llm,hardware,inference,gpu,cli,model-serving
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: py-cpuinfo>=9.0.0
Requires-Dist: nvidia-ml-py>=12.0.0
Provides-Extra: hf
Requires-Dist: huggingface-hub>=0.20.0; extra == "hf"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# tamebi

**Detect your hardware. Know what you can run.**

`tamebi` is a CLI tool that automatically detects your machine's hardware (CPU, RAM, GPU, disk) and tells you exactly which LLM models you can run — with estimated memory usage, throughput, and time to first token.

## Install

```bash
pip install tamebi
```

or with [uv](https://github.com/astral-sh/uv):

```bash
uv pip install tamebi
```

NVIDIA, AMD, and Apple Silicon are all detected automatically — no extra flags or extras needed.

## Quick Start

```bash
tamebi check
```

## CLI Reference

### `tamebi check`

Detect hardware and show what's runnable. Output has three sections:

1. **Hardware** — CPU, RAM, GPU, disk, and available inference memory
2. **Top Recommendations** — the best 3 models for your machine with Ollama run commands
3. **Runnable Models** — all models that fit, with release date, precision, memory breakdown, speed estimate, and TTFT

| Flag               | Short | Default | Description                                                                                           |
| ------------------ | ----- | ------- | ----------------------------------------------------------------------------------------------------- |
| `--json`           | `-j`  | `false` | Output as JSON instead of rich tables                                                                 |
| `--context-length` | `-c`  | `4096`  | Context length in tokens. KV cache scales linearly with this — 4K vs 128K changes memory dramatically |
| `--batch-size`     | `-b`  | `1`     | Concurrent requests. Each gets its own KV cache. Set >1 if planning to serve multiple users           |
| `--verbose`        |       | `false` | Show detailed detection info (driver versions, etc.)                                                  |

### `tamebi models`

Show the full model compatibility matrix — every model in the catalog across all precisions (INT4, INT8, FP16), with fit status and memory at each level.

```bash
tamebi models
```

| Flag               | Short | Default | Description                            |
| ------------------ | ----- | ------- | -------------------------------------- |
| `--context-length` | `-c`  | `4096`  | Context length for KV cache estimation |
| `--batch-size`     | `-b`  | `1`     | Batch size for KV cache estimation     |

### `tamebi update`

Pull the latest model catalog from the remote. The catalog updates automatically in the background but you can force a refresh with this command.

```bash
tamebi update
```

### Examples

```bash
# Basic hardware check
tamebi check

# JSON output for scripting
tamebi check --json

# Estimate for serving 4 concurrent users with 8K context
tamebi check --batch-size 4 --context-length 8192

# Use each model's native max context window instead of the 4K default
tamebi check --context-length 0

# Browse all models and their compatibility across precisions
tamebi models

# Force-refresh the model catalog
tamebi update
```

## Supported Hardware

| Vendor            | Detection Method        | Details                                       |
| ----------------- | ----------------------- | --------------------------------------------- |
| **NVIDIA**        | `nvidia-ml-py` (NVML)   | Model, VRAM, CUDA version, compute capability |
| **AMD**           | `rocm-smi` (subprocess) | Model, VRAM (requires ROCm)                   |
| **Apple Silicon** | `system_profiler`       | Chip model (M1/M2/M3/M4), unified memory      |
| **CPU-only**      | `psutil` + `py-cpuinfo` | Cores, threads, frequency, architecture       |

## Model Catalog

The catalog is automatically updated weekly and covers the latest releases from major labs including Meta, Mistral, Google, Qwen, DeepSeek, GLM, MiniMax, Kimi, Liquid, and AllenAI. Models are fetched directly from HuggingFace Hub — no manual maintenance required.

Run `tamebi update` at any time to pull the latest catalog.

## How Estimation Works

Memory is estimated per model and precision:

```
Total VRAM = Model Weights + KV Cache + Overhead

Model Weights = params (billions) × bytes_per_param
  FP16: 2 bytes | INT8: 1 byte | INT4: 0.5 bytes

KV Cache = 2 × layers × num_kv_heads × head_dim × context_len × bytes × batch_size
  (GQA-aware: uses KV heads, not Q heads)

Overhead = 15% of weights (activations + fragmentation) + 0.5 GB (NVIDIA only)
```

Performance estimates (tokens/sec, time to first token) are based on hardware-class lookup tables. They show ranges, not exact numbers — actual performance depends on drivers, software stack, and workload.

## License

Copyright (c) 2026 Tamebi. All rights reserved. Proprietary and confidential.
