Skip to content
Village

researcher-profiles

A portable format specification and SDK for on-disk researcher profiles.

A researcher profile is a directory of files describing one researcher — their metadata, their papers, their expertise, and (optionally) an embedding index over their work. This package defines what a valid profile is and gives you everything you can do with one: load it, validate it, query it, serve it over HTTP, and load it into a SQL database.

The package is creation-method-agnostic. It does not build profiles; it defines and validates the format. A conforming profile directory can be produced by any process that emits the format — by hand, by script, or by a generation pipeline.

Install

Section titled “Install”
Terminal window
pip install researcher-profiles                  # core: models + wire schemas + openalex parser
pip install researcher-profiles[embeddings]      # + vector store, semantic search, registry ranking
pip install researcher-profiles[client]          # + RemoteResearcherProfile HTTP client
pip install "researcher-profiles[api,embeddings]"  # serve the FastAPI app (incl. /api/v1/match)
pip install researcher-profiles[llm]             # + Anthropic-backed .ask / .review / .innovate / .riff
pip install researcher-profiles[sql]             # + SQLModel relational layer

Core depends only on pydantic and pyyaml. A plain import researcher_profiles never pulls in sqlite-vec, httpx, anthropic, or sentence-transformers. See the Python API reference for the per-extra capability matrix.

Documentation map

Section titled “Documentation map”

This documentation is organized into four types. Pick the one that matches what you need right now.

Tutorial — learning by doing

Section titled “Tutorial — learning by doing”
  • Getting started — build a tiny profile by hand, load it, explore it in Python, and index it for search.

How-to guides — solving a specific task

Section titled “How-to guides — solving a specific task”

Reference — looking up facts

Section titled “Reference — looking up facts”
  • CLI — every subcommand and flag
  • HTTP API — every endpoint and wire model
  • JSON Schemas — the schema files in schemas/
  • Python API — key classes and functions

Explanation — understanding the design

Section titled “Explanation — understanding the design”
  • The profile format — the on-disk bundle layout, the schema_version gate, the depth levels (lite/full/deep) — persona features require a full/deep profile — and why the package is a spec plus SDK.

License

Section titled “License”

MIT.