Can I embed MediaFind's search engine in my own app?

Not yet. MediaFind's engine has a typed Python SDK (mediafind.core.Engine) and a versioned HTTP API (/api/v1) over the same local engine as the desktop app and MCP server, both on-device with no API keys, but the package isn't publicly installable yet. AI agents can use the MCP server built into the MediaFind app today.

Can I run it on-prem?

The engine supports it: 'mediafind serve' exposes the HTTP API, bound to localhost by default; 'mediafind serve --host 0.0.0.0' serves it on your network and requires a bearer token you set via MEDIAFIND_AUTH_TOKEN plus TLS (or an explicit --allow-insecure-lan to accept the risk). The command line that runs it isn't publicly installable yet.

MediaFind SDK & API — embed private, on-device media search

Q: Does the SDK or API send data to the cloud?

No. Indexing, search, transcript reads, and grounded Ask all run against a local index with no network calls; Ask can use a local, keyless LLM. You choose the trust boundary.

Q: Is the API stable enough to build on?

The mediafind.core SDK and the /api/v1 HTTP routes are a versioned, stability-promised contract: new optional fields may be added, but existing ones will not change or be removed without a major-version bump. The package ships a PEP 561 py.typed marker.

The same engine behind the MediaFind app — transcription, semantic search, and grounded Ask — as a typed Python SDK and a versioned HTTP API. On-device, keyless, on-prem-ready. Nothing uploaded.

One engine, three surfaces. The Python SDK, the /api/v1 HTTP API, and the MCP server all run the same local engine as the desktop app and CLI — so a library you index once is reachable from whichever surface fits your stack.

Python SDK

Not publicly installable yet. The Python SDK and the mediafind command line (which runs mediafind serve below) aren't on PyPI yet: the mediafind package there is a placeholder that holds the name, not this SDK. To connect an AI agent today, use the MCP server built into the MediaFind app — see the agent setup guide.

This is what the SDK looks like. Heavy models load lazily, so import mediafind stays cheap:

from mediafind import Engine

with Engine() as mf:                      # default library (respects MEDIAFIND_DATA)
    mf.index("~/Movies")                  # transcribe + embed a file or folder
    hits = mf.search("the part about pricing", k=5)
    answer = mf.ask("what did we decide about pricing?")
    print(answer["answer"], answer["citations"])

Point at a specific library with Engine("/path/to/index.sqlite3"). Optional capabilities (CLIP visual search, a local LLM for Ask, faces) are used when they're installed, and the engine degrades gracefully without them.

Method	Returns	What it does
`index(paths, **opts)`	summary dict	Transcribe + embed a file, folder, or list.
`search(query, k=5, …)`	list of hits	Semantic search over transcript segments with timestamps.
`ask(question, …)`	answer dict	Grounded Q&A with cited sources (a local LLM when installed, else extractive).
`transcript(media_path)`	dict	Transcript, summary, and segments for one indexed file.
`status()`	dict	Entitlement (Pro/free/trial), index quota, and version.

HTTP API

Prefer to call it over the wire, or embed from a non-Python stack? Start the local server and hit the versioned /api/v1 routes:

mediafind serve            # local HTTP API on http://localhost:8000

curl -X POST http://localhost:8000/api/v1/search \
  -H 'content-type: application/json' \
  -d '{"query": "the part about pricing", "k": 5}'

Endpoint	What it does
`POST /api/v1/search`	Semantic / multimodal search; ranked clips with timestamps.
`POST /api/v1/ask`	Grounded answer with cited sources + timestamps.
`GET /api/v1/transcript`	Transcript, summary, and segments for one indexed file.
`GET /api/v1/status`	Entitlement, index quota, and engine version.

/api/v1 is a frozen, versioned contract — separate from the app's internal routes — so you can build against it and not chase UI changes. Request and response shapes are typed; new optional fields may be added, but existing ones won't change without a major-version bump.

On-prem. mediafind serve binds to localhost by default. To serve it across your network, run mediafind serve --host 0.0.0.0: a non-loopback bind requires a bearer token you set via MEDIAFIND_AUTH_TOKEN, plus TLS (--ssl-keyfile/--ssl-certfile) — or an explicit --allow-insecure-lan to accept the risk.

Stays on your machine

Indexing, search, transcript reads, and Ask all run against a local index with no network calls; Ask stays keyless — a local LLM synthesizes answers when one is installed, otherwise you get a cited extractive answer. There are no API keys and no per-call cloud costs. A free tier caps indexed files; a Pro subscription unlocks unlimited indexing and the Pro-only channels. Engine.status() (or GET /api/v1/status) reports the current entitlement.

Embed private, on-device media search in your own app.

Python SDK

HTTP API

Stays on your machine

Build private media search into your product.