Metadata-Version: 2.4
Name: embx-cli
Version: 0.1.0
Summary: Multi-provider embeddings CLI
Project-URL: Homepage, https://github.com/vicmcorrea/embx
Project-URL: Repository, https://github.com/vicmcorrea/embx
Project-URL: Issues, https://github.com/vicmcorrea/embx/issues
Author: embx contributors
License: MIT
License-File: LICENSE
Keywords: cli,embeddings,huggingface,ollama,openai,openrouter,voyage
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: rich<14.0.0,>=13.7.1
Requires-Dist: typer<1.0.0,>=0.12.3
Provides-Extra: dev
Requires-Dist: pytest-cov<6.0.0,>=5.0.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.2.0; extra == 'dev'
Requires-Dist: ruff<0.7.0,>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# embx

`embx` is a multi-provider embeddings CLI for quick experimentation and automation.

## Why this exists

- Use one command surface across OpenAI, OpenRouter, Voyage, and Ollama.
- Keep output script-friendly (`json`, `jsonl`) but readable by default.
- Add cache and config layering so provider switching is painless.

## Install

```bash
pip install -e .
```

## Quick start

```bash
# Show providers
embx providers

# Interactive setup flow
embx connect

# Configure multiple providers in one run and test connectivity
embx connect --all --test

# Test one provider in non-interactive mode
embx connect --provider openrouter --api-key "$EMBX_OPENROUTER_API_KEY" --non-interactive --test

# Configure HuggingFace provider
embx connect --provider huggingface --api-key "$EMBX_HUGGINGFACE_API_KEY" --non-interactive

# List available embedding models
embx models --provider openrouter
embx models --provider openrouter --format json

# HuggingFace model discovery (remote/local/all)
embx models --provider huggingface --source remote --search mini --limit 10
embx models --provider huggingface --source local

# Select one model id for shell pipelines
embx models --provider openrouter --pick 1
embx models --provider openrouter --choose

# Interactive model browsing
embx models --interactive

# Interactive config editing
embx config set
embx config set --key default_provider --value huggingface --non-interactive

# Check provider configuration and readiness
embx doctor
embx doctor --only-configured --check-network
embx doctor --only-configured --check-auth

# Optional: initialize config manually
embx config init

# Embed a single text (argument)
embx embed "vector databases are useful"

# Embed from stdin
printf "semantic search" | embx embed --format json

# Embed as CSV
embx embed "semantic search" --format csv

# Batch embed line-delimited file
embx batch inputs.txt --format jsonl --output outputs.jsonl

# Compare providers for the same input
embx compare "semantic retrieval" --providers openai,openrouter,voyage,ollama

# Compare in machine-readable mode
embx compare "semantic retrieval" --format json --output compare.json

# Rank providers by latency or cost
embx compare "semantic retrieval" --providers openai,voyage --rank-by latency

# Rank providers by embedding agreement quality
embx compare "semantic retrieval" --providers openai,voyage,ollama --rank-by quality

# Emit CSV for spreadsheets or BI tools
embx compare "semantic retrieval" --providers openai,voyage --format csv
embx batch inputs.txt --format csv --output embeddings.csv

# Skip providers without configured credentials
embx compare "semantic retrieval" --providers openai,voyage,ollama --only-configured

# Show top 2 ranked providers and hide failed rows
embx compare "semantic retrieval" --rank-by quality --top 2 --hide-errors

# Markdown table output
embx compare "semantic retrieval" --format md

# Retries with backoff for transient provider failures
embx embed "semantic retrieval" --provider openrouter --retries 2 --retry-backoff 0.2

# HuggingFace embeddings inference
embx embed "semantic retrieval" --provider huggingface --model sentence-transformers/all-MiniLM-L6-v2
```

## Config precedence

1. CLI flags
2. Environment variables (`EMBX_*`)
3. Config file (`~/.config/embx/config.json`)
4. Built-in defaults

## Shell completions

Typer provides completion out of the box:

```bash
embx --install-completion
embx --show-completion
```

## Current status

- Core command scaffolding is implemented.
- Provider integrations are intentionally minimal and extensible.
- `compare` command is available for side-by-side provider checks.
- Docs in `docs/` explain architecture and roadmap.
