Skip to main content

hull — shared core for the wet / crg / mnemo self-hosted stack

CI CodeQL

Python License

hull is the shared monorepo core for the wet, crg and mnemo self-hosted stack.

It owns everything the three products share — token auth, per-task model configuration, per-user rate limiting, local SQLite storage, the HTTP MCP server lifecycle, web scraping/search infrastructure, and a local embedding daemon — for wet (search), crg (code graph) and mnemo (memory).

Install

hull ships as one PyPI dist, n24q02m-hull. The wheel carries all three import packages; the heavy stacks are opt-in extras:

pip install n24q02m-hull               # hull_core only (crg, mnemo)
pip install "n24q02m-hull[web]"        # + hull_web scraping/browser stack (wet)
pip install "n24q02m-hull[embedding]"  # + hull_embedding_daemon server stack
pip install "n24q02m-hull[mteb]"       # + pyarrow for model_selection MTEB fetchers
pip install "n24q02m-hull[embedding,embedding-gguf]"  # + llama.cpp runtime for *-GGUF models

import hull_web without the [web] extra raises ImportError naming the missing modules and the install command.

The TypeScript core ships to npm as @n24q02m/hull, at the same version as the PyPI dist (see packages/core-ts):

npm install @n24q02m/hull

Packages

Source dir Import package Extra Purpose
packages/core-py hull_core (base; MTEB boards need [mteb]) Auth (3 modes), per-task model cells, limiter, ~/.hull/ SQLite WAL storage, server start + /mcp endpoint, CLI, SSRF-safe HTTP, lifecycle lock, model_selection leaderboard picker + runtime registry (refresh → eval-on-change → promote)
packages/embedding-daemon hull_embedding_daemon [embedding] Local ONNX/GGUF embedding server (FastAPI)
packages/web hull_web [web] Search (SearXNG), scraping strategies, stealth browsers, fingerprinting, HTTP/SSRF security
packages/core-ts @n24q02m/hull (npm) n/a TypeScript core: MCP Streamable HTTP transport, OAuth 2.1 authorization server, credential storage, relay client

Runtime model

  • Python 3.13. Dev with uv, always-on with docker.
  • hull server start is the only way to run a server; MCP is an HTTP endpoint at http://host:port/mcp — never a spawned subprocess.
  • The CLI is the control plane + consumer. With the server down the CLI tells you to start it first; there is no hidden local-core mode.
  • Provider calls are plain OpenAI-spec HTTP (httpx). OpenRouter is the pre-wired default. Each task (embed, rerank, chat, jev_score) has its own base_url + api_key + model cell — change provider by editing config, never code.
  • Storage is local SQLite (WAL) under ~/.hull/. Backup/sync is rclone outside this repo.

Auth — one mechanism, three modes

Mode is a config state ([server] auth in ~/.hull/config.toml):

  1. no-auth — localhost-only bind enforced, one shared namespace.
  2. token — one shared token (token_hash in config), still one shared namespace.
  3. multi — users.toml maps uid → {token_hash, enabled, namespace, allowed_roots, limits}; one process serves N users, each isolated to their namespace. Admin is host-side only: edit users.toml, restart.

Token hashes are scrypt (hull token hash). Wrong token → 401; disabled user → 403; over-limit → 429.

Quick start

uv sync
uv run hull config init          # write ~/.hull/config.toml (OpenRouter defaults)
uv run hull token hash mysecret  # mint a token_hash for users.toml / config
uv run hull server start         # serves http://127.0.0.1:8000/mcp

Development

uv sync --all-extras
uv run pytest -q
uv run ruff check .
uv build

License

Apache-2.0

Metadata

Release files for hull-core 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hull-core 0.4.0
File Size Uploaded Provenance Actions
hull_core-0.4.0.tar.gz 979.5 kB With provenance Details for hull_core-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hull-core 0.4.0
File Interpreter ABI Platform Actions
hull_core-0.4.0-py3-none-any.whl Python 3 none any Details for hull_core-0.4.0-py3-none-any.whl

Total release size: 1.2 MB

Release files / hull_core-0.4.0.tar.gz

Download URL hull_core-0.4.0.tar.gz
Size 979.5 kB
Tags Source
SHA-256 checksum
How to use checksums
7e59a569aec619ab604b338537737ceba8767b7e25fe3b7c7eab887a78c37e0d
BLAKE2b-256 checksum
How to use checksums
3ab7bcfe3a539a0203c9fb0df4bb3ef4d14505aab98c94e3e38c43b9373179fb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / hull_core-0.4.0-py3-none-any.whl

Download URL hull_core-0.4.0-py3-none-any.whl
Size 210.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e48fa0e6b93e7ee05642df91428ebca5daa7bf865f7593774fa1b6225509d836
BLAKE2b-256 checksum
How to use checksums
3ead2cbda63b59dbf85817c5658228c0e22d7563d5bf8a65157868ca5b6d5443
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Security for hull-core 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hull_core-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page