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, and web scraping/search infrastructure — for wet (search), crg (code graph) and mnemo (memory).

Install

hull ships as one PyPI dist, n24q02m-hull. The wheel carries both python 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[mteb]"       # + pyarrow for model_selection MTEB fetchers

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

hull does not run models. The shared embed/rerank HTTP service is pip install "fastretrieval[server]" (fastretrieval-server, serving /embed + /rerank); hull callers reach it over HTTP.

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/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, token-table auth (token, multi), buildCli console builder, encrypted credential storage, lockfiles and cache

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 config set server.port 8771   # edit one key in place, comments intact
uv run hull config get server.port        # print one key (secrets are not echoed)
printf '%s' "$TOKEN" | uv run hull token hash  # mint a token_hash for users.toml / config
uv run hull status                    # auth mode, bind, DB path
uv run hull doctor                    # python / config / users.toml checks
uv run hull server start              # serves http://127.0.0.1:8000/mcp

hull token hash reads the token from piped stdin or a hidden prompt; a token on the command line is refused, because it would land in shell history. hull --version prints the installed version, and hull <command> -h lists that command's flags.

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.6.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.6.0
File Size Uploaded Provenance Actions
hull_core-0.6.0.tar.gz 821.1 kB With provenance Details for hull_core-0.6.0.tar.gz

Built distribution (wheel)

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

Total release size: 1.0 MB

Release files / hull_core-0.6.0.tar.gz

Download URL hull_core-0.6.0.tar.gz
Size 821.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a84339ca1d1b0946333b8c1289d73aee674f4ad02f04aa9f2fe6aab4d47d951a
BLAKE2b-256 checksum
How to use checksums
7142ee89886088c8db3044197ba8d697b078ba4dc560a46bb4e18111e19255aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 12, 2026.

Transparency log

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

Download URL hull_core-0.6.0-py3-none-any.whl
Size 227.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3e7169574f8367c51bd7101cbecfc127aa50b90637e56c904d86e42144c10983
BLAKE2b-256 checksum
How to use checksums
8109b976def31a038f6040fe5dfaf51171d3f99a79951f4f8fc0ec569c334a14
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 12, 2026.

Transparency log

Security for hull-core 0.6.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.6.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 Nov 12, 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