Metadata-Version: 2.4
Name: langchain-voxell
Version: 0.1.0
Summary: LangChain embeddings for Forge — Voxell's text-embedding API (turbo/pro/ultra; ultra = Qwen3-Embedding-8B, ~75+ avg MTEB, #4 English).
Project-URL: Homepage, https://voxell.ai/forge
Project-URL: Repository, https://github.com/VoxellInc/langchain-voxell
Project-URL: Issues, https://github.com/VoxellInc/langchain-voxell/issues
Author: Voxell, Inc.
License: MIT
License-File: LICENSE
Keywords: embeddings,forge,langchain,qwen3,rag,semantic-search,voxell
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain-core>=0.3.0
Description-Content-Type: text/markdown

# langchain-voxell

LangChain embeddings for [**Forge**](https://voxell.ai/forge) — Voxell's hosted text-embedding API.

## Why Forge

One API, three tiers — pick your point on the quality/cost curve:

| Model | Dim | Notes |
| ----- | --- | ----- |
| `turbo` | 1024 | fast, low cost |
| `pro` | 2560 | |
| `ultra` | 4096 | Qwen3-Embedding-8B; ~75+ avg task score on MTEB, currently #4 on MTEB (English) — the top *usable* model (the three above are research-only) |

Matryoshka (MRL) dimensions are real: truncated vectors are re-normalized, so a shorter `dim` is a
unit-norm prefix of the full vector — smaller index, minimal quality loss. Forge logs request
metadata only (model, tokens, latency) — never your text or vectors.

## Install

```bash
pip install langchain-voxell
```

## Usage

```python
from langchain_voxell import ForgeEmbeddings

# FORGE_API_KEY is read from the environment; or pass api_key=...
emb = ForgeEmbeddings(model="turbo")

doc_vectors = emb.embed_documents(["the quick brown fox", "lazy dog"])
query_vector = emb.embed_query("fast animal")
```

`embed_query` and `embed_documents` set the Forge `input_type` (`query` / `document`) for you.

### Async

```python
vectors = await emb.aembed_documents(["alpha", "beta"])
q = await emb.aembed_query("a search query")
```

### Matryoshka (shorter vectors)

```python
emb = ForgeEmbeddings(model="turbo", dimensions=256)  # re-normalized 256-d vectors
```

### With a vector store

```python
from langchain_community.vectorstores import FAISS
from langchain_voxell import ForgeEmbeddings

store = FAISS.from_texts(["doc one", "doc two"], ForgeEmbeddings(model="pro"))
hits = store.similarity_search("query", k=2)
```

## Configuration

| Arg | Default | Notes |
| --- | ------- | ----- |
| `model` | `"turbo"` | `turbo` \| `pro` \| `ultra` |
| `api_key` | `FORGE_API_KEY` env | get one at [dash.voxell.ai](https://dash.voxell.ai) |
| `base_url` | `https://api.voxell.ai` | |
| `dimensions` | `None` | Matryoshka truncation, e.g. `256` |
| `timeout` | `30.0` | seconds |

## License

MIT © Voxell, Inc.
