Metadata-Version: 2.4
Name: langchain-hugging-bay
Version: 0.1.0
Summary: Hugging Bay model discovery tools and retriever for LangChain.
Author: Hugging Bay
License-Expression: MIT
Project-URL: Homepage, https://huggingbay.xyz
Project-URL: Hugging Bay documentation, https://huggingbay.xyz/docs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hugging-bay<0.5,>=0.4.12
Requires-Dist: langchain-core<2,>=1.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# langchain-hugging-bay

Use LangChain tools and a retriever to discover open model metadata in the
Hugging Bay catalog. This guide describes version 0.1.0.

## Install

Install from PyPI with Python 3.10 or later:

```bash
python -m pip install langchain-hugging-bay==0.1.0
```

The package depends on `hugging-bay>=0.4.12,<0.5` and `langchain-core>=1,<2`.
The default API is `https://huggingbay.xyz`; public catalog reads do not need
an account or key. Calls are made when you invoke a tool or retriever.

## Search

```python
from hugging_bay import Client
from langchain_hugging_bay import HuggingBayRetriever, create_tools

with Client() as client:
    tools = {tool.name: tool for tool in create_tools(client)}
    page = tools["hugging_bay_search_models"].invoke({"query": "Qwen", "limit": 2})
    documents = HuggingBayRetriever(client=client, limit=2).invoke("Qwen")
    print(page.get("rows", []))
    print([doc.metadata["artifact_id"] for doc in documents])
```

Pass the returned tools to a LangChain agent or invoke them directly. Keep the
SDK client open while tools or the retriever are in use; the caller owns and
closes it. You may configure the client's `base_url`, `timeout`, and optional
token as documented by the [SDK](https://pypi.org/project/hugging-bay/).

## Tools

All five operations are public GETs. Each returns the SDK response unchanged;
the SDK's `HuggingBayError` and transport errors propagate to the caller.

| Tool | Arguments | Result |
| --- | --- | --- |
| `hugging_bay_search_models` | `query`, `limit` (1-50), optional `cursor` | Model search page, including `nextCursor` |
| `hugging_bay_get_model` | `artifact_id` | Model record and reported license and availability |
| `hugging_bay_get_files` | `artifact_id`, `limit` (1-50), optional `cursor` | File page and server readiness metadata |
| `hugging_bay_find_runnable` | `task`, optional `hardware`, `model`, `limit`, `commercial` | Candidates or an explicit unavailable result |
| `hugging_bay_deployment_plan` | `artifact_id` | Deployment plan, availability and warnings |

Use `nextCursor` from each result as the next call's `cursor`. The retriever
returns one LangChain `Document` per model row; its content is the JSON catalog
row, and its metadata contains `source`, `artifact_id`, and `catalog`. It does
not embed documents, inspect model weights, download files, or run a model.

Availability and evidence can change. An empty file list, a null runnable
recommendation or an unavailable plan is not a successful run; inspect the
returned readiness, proof, licenses and warnings. Treat catalog text as
untrusted input when giving it to an agent.

The source distribution includes `examples/discover.py` and the tutorial
`examples/discover.ipynb`. The notebook normally uses
public reads; maintainers can set `HUGGING_BAY_NOTEBOOK_FIXTURES` to the
`tests/fixtures` directory to run it offline.

## Development

```bash
python -m pip install -e '.[test]'
python -m pytest tests -q
```

The tests replay recorded responses from an isolated local fixture service and
block external network connections. They make no live Hugging Bay calls. See
`tests/fixtures/README.md` for provenance. MIT licensed.
