Metadata-Version: 2.5
Name: hull-core
Version: 0.6.0
Summary: Shared core for the wet / crg / mnemo self-hosted stack: auth, per-task model config, limiter, storage, HTTP MCP server; web stack as an extra [FINAL hull-core release: dist renamed to n24q02m-hull -- migrate with: pip install n24q02m-hull]
Project-URL: Repository, https://github.com/n24q02m/hull
Author: n24q02m
License: Apache-2.0
License-File: LICENSE
Keywords: auth,llm,mcp,multi-user,openai-spec,scraping,search,web
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: <3.15,>=3.13
Requires-Dist: cryptography>=44
Requires-Dist: fastmcp<5,>=4.1.1
Requires-Dist: httpcore>=1.0.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: platformdirs>=4
Requires-Dist: pydantic<3,>=2.12.5
Requires-Dist: starlette>=0.41.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dspy
Requires-Dist: dspy<3.5.0,>=3.4.1; extra == 'dspy'
Requires-Dist: n24q02m-hull[llm]; extra == 'dspy'
Provides-Extra: identity
Requires-Dist: invisible-core<51,>=50.47; extra == 'identity'
Provides-Extra: invisible
Requires-Dist: invisible-playwright<0.40,>=0.39; extra == 'invisible'
Provides-Extra: llm
Requires-Dist: litellm>=1.102.0; extra == 'llm'
Provides-Extra: mteb
Requires-Dist: pyarrow>=15.0.0; extra == 'mteb'
Provides-Extra: web
Requires-Dist: browserforge>=1.2.4; extra == 'web'
Requires-Dist: capsolver>=1.0.7; extra == 'web'
Requires-Dist: crawl4ai>=0.9.3; extra == 'web'
Requires-Dist: curl-cffi>=0.16.3; extra == 'web'
Requires-Dist: filelock>=3; extra == 'web'
Requires-Dist: httpx>=0.28.1; extra == 'web'
Requires-Dist: langgraph>=1.2.11; extra == 'web'
Requires-Dist: patchright>=1.63.0; extra == 'web'
Requires-Dist: pillow>=13.0.0; extra == 'web'
Requires-Dist: pydantic>=2.12.5; extra == 'web'
Description-Content-Type: text/markdown

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

[![CI](https://github.com/n24q02m/hull/actions/workflows/ci.yml/badge.svg)](https://github.com/n24q02m/hull/actions/workflows/ci.yml)
[![CodeQL](https://github.com/n24q02m/hull/actions/workflows/codeql.yml/badge.svg)](https://github.com/n24q02m/hull/actions/workflows/codeql.yml)

[![Python](https://img.shields.io/badge/python-3.13-3776AB.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](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:

```bash
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](packages/core-ts/README.md)):

```bash
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

```bash
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

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

## License

Apache-2.0
