Hashgrid DNA (local)

hashgrid

フィードバックから学習する検索エンジン、Hashgrid DNA 用の Python クライアントです。アイテムを追加して検索し、結果を評価します。DNA はその評価から学習するため、次の検索ではより適切な順位で結果が表示されます。

DNA が扱うのは埋め込みベクトルのみで、コンテンツを見ることはありません。このパッケージはお使いのマシン上でテキストと画像を埋め込み、DNA にはベクトルのみを送信します。コンテンツはローカルインデックスに保存され、お手元に残ります。

pip install 'hashgrid[local]'

[local] を指定すると、アカウント不要で CPU 上で動作するローカル埋め込み機能が追加されます。代わりに OpenAI または Voyage で埋め込みを行うには、hashgrid のみをインストールし、ご自身のキーを使用してください。

各グリッドには専用の API キー（hg-…）があります。グリッドの作成にキーは必要ありません。

from hashgrid.dna import Grid

grid, api_key = Grid.create("mine")
print(api_key)   # shown only now: keep it, e.g. as $HASHGRID_API_KEY

この方法で作成したグリッドには、最大 1024 件のアイテムとクエリを登録できます（grid.dna.get_grid().max_nodes）。各アドレスで 1 日に作成できるグリッド数には上限があります。上限を増やすには [email protected] までご連絡ください。

追加、検索、評価

from hashgrid.dna import Grid

grid = Grid()  # Index() and DNA(), from the environment: the key from $HASHGRID_API_KEY

grid.add_many({
    "/cities/lisbon": "Lisbon, a hilly coastal capital",
    "/cities/oslo": "Oslo, between fjords and forest",
})

query, results = grid.ask("a capital by the sea", k=2, prefix="/cities/")
results[0].content                    # "Lisbon, a hilly coastal capital"
grid.score(query, results[0], 1.0)    # a good result
grid.score(query, results[1], -0.5)   # a poor one

• アイテムには、グリッド内で一意なパスである key があります。検索で見つかるのはアイテムのみで、prefix を指定すると、その文字列で始まるキーに検索対象を絞り込めます。キーを指定しない場合、アイテムにはコンテンツのハッシュがキーとして設定されるため、同じコンテンツを再度追加すると同じアイテムが返されます。
• クエリにはキーがありません。grid.search(query, k) を実行すると、これまでに表示されていない次の k 件の結果が返されます。
• 評価は -1（不正解）から 1（完璧）までです。結果を評価することも、良いまたは悪いと分かっている任意のペアを評価することもできます。DNA の学習に使われるのは評価のみです。

各 Result には、アイテムの id、key、インデックスから取得した content、および指定した score が含まれます。grid.results(query) はクエリのこれまでの結果を一覧表示し、grid.get と grid.delete はアイテムまたはその ID を受け取ります。grid.delete_grid() はグリッド全体を完全に削除し、インデックス内のコンテンツも削除します。AsyncGrid でも同じ操作を await 付きで実行できます。

画像

コンテンツには、テキストまたはファイルやバイト列から作成した Image を使用できます。画像には、画像を受け取る埋め込み機能が必要です。

from hashgrid.dna import Grid
from hashgrid.index import Image, Index

grid = Grid(Index("fastembed:Qdrant/clip-ViT-B-32"))
grid.add(Image("photos/beach.jpg"), key="/photos/beach")
query, results = grid.ask("a sunny beach", k=5)      # text finds images
query, results = grid.ask(Image("another.jpg"))      # and so do images

インデックス

Index はグリッドのローカル側です。コンテンツを埋め込み、DNA の ID に対応付けて sqlite に保存するため、結果とともにコンテンツを取得できます。Index() はデフォルトの埋め込み機能と ~/.hashgrid/index.sqlite を使用します。$HASHGRID_EMBEDDER と $HASHGRID_INDEX、または引数で変更できます。

Index("voyage:voyage-multimodal-3")
Index(OpenAI("text-embedding-3-small", dimensions=512), path="my-index.sqlite")
Index(path=":memory:")   # keeps nothing

グリッドごとに使用する埋め込み機能は 1 つにしてください。異なるモデルのベクトルは比較できません。インデックスには各グリッドの埋め込み機能が記録され、別の埋め込み機能を使用すると拒否されます。また、グリッドは自身のベクトル長と異なるベクトルを拒否します。

埋め込み機能	対応する入力	実行場所	必要なもの
fastembed:BAAI/bge-small-en-v1.5（デフォルト）	テキスト	ローカル	hashgrid[local]
fastembed:Qdrant/clip-ViT-B-32、fastembed:jinaai/jina-clip-v1	テキスト、画像	ローカル	hashgrid[local]
openai:text-embedding-3-small	テキスト	OpenAI	OPENAI_API_KEY
voyage:voyage-3.5	テキスト	Voyage AI	VOYAGE_API_KEY
voyage:voyage-multimodal-3	テキスト、画像	Voyage AI	VOYAGE_API_KEY

その他の fastembed、OpenAI、Voyage のモデルも使用できます。指定形式は fastembed:<model>、openai:<model>、voyage:<model> です。DNA が受け取れる値は最大 2048 個のため、openai:text-embedding-3-large は 2048 個に短縮されます（openai:<model>@<n> で長さを指定できます）。OpenAI または Voyage を使用する場合、コンテンツはご自身のキーを使って各プロバイダーに送信されますが、DNA に送信されることはありません。独自の埋め込み機能には、spec、受け取る modalities（{"text"}、{"text", "image"}）、および embed(contents, kind) を備えた任意のオブジェクトを使用できます。kind は "document" または "query" です。

型付き API

DNA と AsyncDNA には、HTTP API の各ルートに対応するメソッドがあり、ルート名にちなんだ名前が付いています。

from hashgrid.dna import DNA

dna = DNA("hg-…")
item = dna.create_node([0.1, 0.2, 0.3], key="/items/1")
query = dna.create_node([0.1, 0.2, 0.25])
edge = dna.create_edge(query, prefix="/items/")   # the search; None when nothing is left
dna.put_edge(query, edge, 1.0)                    # the score

メソッド	ルート
create_grid(name), acreate_grid(name)（関数、キー不要）	POST /
get_grid()	GET /
delete_grid()	DELETE /
list_nodes(cursor, limit), iter_nodes()	GET /nodes
get_node(nid)	GET /nodes/{nid}
create_node(emb, key=None)	POST /nodes
update_node(nid, key=…, emb=…)	PATCH /nodes/{nid}
delete_node(nid)	DELETE /nodes/{nid}
list_edges(nid, cursor, limit), iter_edges(nid)	GET /nodes/{nid}/edges
get_edge(nid, eid)	GET /nodes/{nid}/edges/{eid}
create_edge(nid, prefix="")、別名 search	POST /nodes/{nid}/edges
put_edge(nid, eid, score)、別名 score	PUT /nodes/{nid}/edges/{eid}
update_edge(nid, eid, score)	PATCH /nodes/{nid}/edges/{eid}
delete_edge(nid, eid)	DELETE /nodes/{nid}/edges/{eid}

ID は16文字の16進文字列です。メソッドには、Node または Edge 自体を渡すこともできます。エラーは DNAError のサブクラスである Unauthorized（401）、Forbidden（403：グリッドのノード上限に達している、またはグリッドが凍結されている）、NotFound（404）、Conflict（409、キーが使用済み）、Invalid（422）、TooManyRequests（429：お使いのアドレスから作成されたグリッドが多すぎます。時間をおいて再試行してください）です。

MCP サーバー

hashgrid-mcp は、テキストや画像を扱うエージェント向けの、stdio 経由で動作するローカル MCP サーバーです。埋め込み処理はお使いのマシン上で行い、DNA にはベクトルのみを送信し、コンテンツはローカルインデックスに保持します。

{
  "mcpServers": {
    "hashgrid": {
      "command": "uvx",
      "args": ["--from", "hashgrid[local]", "hashgrid-mcp"],
      "env": { "HASHGRID_API_KEY": "hg-…" }
    }
  }
}

Claude Code を使う場合：

claude mcp add hashgrid -e HASHGRID_API_KEY=hg-… -- uvx --from 'hashgrid[local]' hashgrid-mcp

キーがない場合、エージェントは create_grid を呼び出せます。サーバーがグリッドを作成し、そのキーをローカルインデックスに保存して、以降はそのキーを使用します。

ツール：

• add_item(text | image, key?)：テキスト、または画像ファイルのパスをアイテムとして追加します。
• search(query | image, k, prefix)：テキストまたは画像のパスとともに、最も関連性の高い結果を返します。
• more_results(query_id, k, prefix)：次の結果を返します。
• score(query_id, item_id, score)：結果にスコアを付けます。
• delete_item(item_id)：アイテムを削除します。
• create_grid(name)：サーバーにキーがない場合にグリッドを作成します。
• delete_grid(confirm)：グリッドを完全に削除します。confirm にはグリッド名を指定します。

初回の呼び出し時に、約70 MBのローカルモデルがダウンロードされます。画像を使う場合は、HASHGRID_EMBEDDER=fastembed:Qdrant/clip-ViT-B-32 を設定してください。

変数	デフォルト
HASHGRID_API_KEY	create_grid がインデックスに保存したキー
HASHGRID_EMBEDDER	fastembed:BAAI/bge-small-en-v1.5。openai:… または voyage:… を使う場合は、uvx --from hashgrid hashgrid-mcp だけで十分です
HASHGRID_INDEX	~/.hashgrid/index.sqlite
HASHGRID_DNA_URL	https://dna.hashgrid.ai/api/v1

サーバーは各グリッドの埋め込みモデルをインデックスに記録し、そのグリッドに別のモデルを使用することを拒否します。

ホスト型サーバー https://dna.hashgrid.ai/mcp が受け取るのはコンテンツではなくベクトルです。エージェントが独自に埋め込みを生成する場合に使用してください。

ライセンス

MIT