Python API reference

Key classes and functions in researcher_profiles. The core install (pydantic + pyyaml) provides the schema models, ResearcherProfile, and the OpenAlex parser. Other surfaces attach or import only when their extra is present.

For the narrative behind the module layout, the storage interface, the capability managers, and the export idempotency contract, see the developer notes in docs-dev/rp-sdk/explanation/sdk-architecture.md.

Capability by extra

Surface	Import	Extra
Schema models, ResearcherProfile, OpenAlex parser	researcher_profiles	core
resolve_person	researcher_profiles.resolve	core
prof.index (SqliteEmbeddingIndex), store.match / .centroids / .indexes	researcher_profiles.embeddings, researcher_profiles.analytics	[vectors,st]
prof.persona (ask / review / innovate / riff / chat)	researcher_profiles.generative	[llm]
ApiArtifactStorage, StaticArtifactStorage, .from_api(), .from_url(), rank_against(), resolve_rid()	researcher_profiles.client	[client]
ProfileStore (protocol), FilesystemProfileStore	researcher_profiles.store	core
create_app	researcher_profiles.api.app	[api]
ArtifactStorage (ABC), DirectoryArtifactStorage	researcher_profiles.profile.storage	core
SqlProfileStore, SqlArtifactStorage, .from_db(), the rp_* tables	researcher_profiles.store.db, researcher_profiles.store.sql	[sql]

Each capability manager is built lazily on first access, so a core-only install still imports the package and a missing extra raises an ImportError naming it at first use. The optional public names (LLMClient, ApiArtifactStorage, SqlProfileStore, …) do the same when accessed.

---

ResearcherProfile

researcher_profiles.ResearcherProfile is a profile loaded from a directory. Persistence goes through a composed ArtifactStorage, and capability managers (prof.persona, prof.index, prof.cite, prof.coverage, prof.topics, prof.edit) hang off the aggregate. Both are described in docs-dev/rp-sdk/explanation/sdk-architecture.md.

class ResearcherProfile(storage: ArtifactStorage, eager: bool = False)

A researcher profile loaded from a directory on disk.

Use from_files as the documented entry point; the bare constructor is the same code path with no validation.

Properties

affiliation: str | None

build_state: BuildState : Build bookkeeping from .build/<slug>/meta/build_state.json.

citations: Any

cite: Any : prof.cite: get, many, verify, export.

coverage: Any : prof.coverage: get, staleness, recent_work, last_updated.

directory: Path | None : The filesystem directory backing this profile, or None.

edit: Any : Owner metadata, SOUL, and visibility changes.

expertise: str

field: str | None

grants: list[GrantRecord] : Grant records from sources/grants.jsonld; empty when absent.

has_persona: bool : Whether this profile can role-play as a synthesized persona.

index: Any : prof.index: build, search, search_similar, embedding.

level: str : Profile depth tier: "lite" / "full" / "deep".

license: str | None : Reuse terms for the published record.

metadata: ProfileDocument : The parsed profile.jsonld document.

name: str

orcid: str | None : Derived from rid; None for a locally-minted identity.

papers: list[PaperRecord]

persona: Any : prof.persona: ask, review, innovate, riff, chat.

provenance: str : Who asserted this profile and on what basis.

rid: str : The identity of this profile: a canonical ORCID or a local: id.

slug: str : Display handle, derived from the profile directory name.

soul: str

storage: ArtifactStorage : The composed backend. Where every artifact of this profile lives.

summaries: Mapping[str, str]

summary: str | None

topics: Any : prof.topics: get, relevance.

Class Methods

from_api(url: str, slug: str | None = None, token: str | None = None, timeout: float = 60.0, client: Any = None)

Construct from a live researcher_profiles.api server.

url may be the server root (e.g. http://localhost:8109), in which case slug must be provided, or a slug-qualified URL like http://localhost:8109/api/v1/profiles/jane-doe.

The returned object is an ordinary ResearcherProfile over an ApiArtifactStorage: read-only, with an HTTP-backed persona and a search-only index. The import is deferred, same shape as from_db, so a core-only install still imports this module.

from_db(engine_or_url: Any, ref: str, eager: bool = False)

Construct from the SQL profile store. Requires the sql extra.

engine_or_url is a SQLAlchemy Engine or a connection URL; ref is a rid or a slug (rid wins, as everywhere)::

prof = ResearcherProfile.from_db("postgresql://…/rp", "jane-doe")

The import below is deferred, the same shape as from_api / from_url: naming this method must not pull SQLAlchemy, which is exactly the cost the sql extra exists to avoid.

from_files(path: str | os.PathLike, eager: bool = False, validate: bool = False)

Construct from a local directory or a published profile URL.

path may also be an http(s):// or s3:// URL pointing at a statically published profile directory, in which case this delegates to from_url.

validate: run the on-disk format check and raise on any error. Off by default: most callers tolerate gaps (missing sources/, missing citations.json, etc.) which are common during profile construction. Requires a local directory.

from_url(url: str, eager: bool = False, timeout: float = 30.0, client: Any = None)

Construct from a published profile directory on a static host.

url points at one profile’s directory, e.g. https://profiles.example.org/jane-doe or s3://my-bucket/profiles/jane-doe (public buckets only; the s3 scheme is translated to the HTTPS endpoint). For a live API server, use from_api instead.

list_remote(url: str, token: str | None = None, timeout: float = 30.0, client: Any = None)

List the profiles a remote server holds.

Returns plain dicts shaped like ProfileSummary. A listing is not a profile, so this is a classmethod on the entry-point class rather than anything on an instance.

Methods

add_post_commit_hook(hook: WriteHook)

Register a callable to run after a write unit commits successfully.

The pre-commit/post-commit distinction is about what a hook is allowed to do, not only when it runs. A pre-commit hook observes a write in progress and may abort it (a raise rolls the unit back). A post-commit hook observes a write that has already landed and must not abort anything, because there is nothing left to roll back. Use this for fire-and-forget notifications to something outside the store (e.g. pushing to an external search index) where blocking, or failing, a profile write on that system’s availability would be wrong.

Fires exactly once per outermost write_unit, after that unit’s own commit. Nested units never fire it, mirroring how pre-commit hooks collapse a batch of writes wrapped in one explicit write_unit into a single hook run. A raising hook is caught and logged at WARNING, never propagated; see _fire_post_commit_hooks.

Registration belongs on the store, not on an HTTP app, for the same reason add_pre_commit_hook does: it must fire for API routes, CLI writes, and out-of-process pipeline writes alike.

add_pre_commit_hook(hook: WriteHook)

Register a callable to run inside every write unit, before commit.

Hooks run in registration order and receive one WriteContext. A hook that raises aborts the write (see write_unit).

Registration belongs on the store, not on an HTTP app: a hook registered here fires for API routes, CLI writes, and out-of-process pipeline writes alike. ProfileStore.add_pre_commit_hook is the store-level entry point that threads hooks onto every profile it hands out.

build_manifest(write: bool = False)

Generate the manifest from what the backend actually holds.

The backend answers with a directory walk for files, the rp_artifacts rows for SQL, or the recorded manifest for a static host, so there is no directory walk here.

With write=True the regenerated hasPart / subjectOf are stored back through save_profile, which stamps dateModified: a manifest whose sha256 entries moved is a real content change and the vintage must follow it.

close()

Release whatever the backend holds open (an HTTP client, say).

A no-op on a backend with nothing to close, so with ResearcherProfile.from_api(...) as prof: works everywhere.

content_hash()

"sha256:<hex>" over the canonical document and the SOUL text.

Store-maintained derived state, refreshed inside the write unit before the pre-commit hooks run, so a hook reading it observes post-write content. Identical across backends by construction.

delete_summary(paper_id: str)

Remove one paper summary body; absent is not an error.

locate(parts: str = ())

A human-readable locator for a logical artifact, display only.

Never parse this, never join to it, never open it. Storage backends return whatever names the artifact best: a path, a URL, a table/row reference. It exists so error messages and CLI output can say where something lives without anyone assuming that where is a directory.

manifest()

The manifest as recorded in profile.jsonld (hasPart + subjectOf).

persisted_document()

The serialized document the store currently holds; {} when absent.

The dateModified comparison basis. Public because an ingest legitimately needs it, though it is not metadata, which is validated and may carry unsaved edits.

refresh()

Drop cached reads so the next access re-fetches.

Clears this profile’s own lazy slots and asks the backend to drop any caching of its own (ApiArtifactStorage holds the combined detail payload).

require_directory(what: str)

The backing directory, or a CapabilityUnavailableError.

The one place a directory-needing capability asks, so the message naming the way out is written once instead of in three backends.

rid_or_empty()

The rid, or "" when no document is readable yet.

A profile being created has no readable document; identity is not a precondition for writing one. Used to name a write unit.

save_build_state(state: BuildState | None = None)

Persist build state; None persists what is in memory.

Build state is separate from published content. A backend may serve published content while having no build state at all. That is exactly what ReadOnlyArtifactStorage.load_build_state models by returning an empty BuildState.

save_citations(data: Any = UNSET)

Persist the citation graph; None deletes it.

Omitting data persists what is in memory. That is why the default is the UNSET sentinel and not None: None is a meaningful value here.

save_expertise(text: str | None = None)

Persist the expertise narrative; None persists what is in memory.

save_grants(grants: list[GrantRecord] | None = None)

Persist the grant records; None persists what is in memory.

save_papers(papers: list[PaperRecord] | None = None)

Persist the paper corpus; None persists what is in memory.

save_profile(doc: ProfileDocument | None = None)

Validate, stamp dateModified, and persist the profile document.

The single write path for the profile document. doc defaults to the current in-memory metadata.

The order matters and is fixed: dump -> stamp against what the store already holds -> canonicalize -> re-validate -> persist. Re-validation happens before the storage hook is called, so a document that would fail to load never reaches the store and the in-memory profile is untouched.

Stamping compares serialized dicts, not models: pydantic prunes None and empty collections, and comparing an un-normalized input against a normalized stored document would report a change on every write (see researcher_profiles.utils.date_modified). Any dateModified already sitting in the dumped document is ignored: it was carried over from whatever was loaded, and honouring it would freeze the stamp at whatever the first build wrote.

Returns the re-parsed ProfileDocument.

save_soul(text: str | None = None)

Persist the SOUL narrative; None persists what is in memory.

save_summary(paper_id: str, text: str)

Persist one paper summary body.

set_paper_contaminated(paper_id: str, contaminated: bool)

Flag a paper contaminated. Returns True if the paper exists.

Contamination is build state, so this mutates .build/<slug>/meta/build_state.json through save_build_state and never touches the published record.

to_agent_seed()

Return the minimal dict an external agent runtime needs to seed an agent row from this profile.

Intended for downstream tools that want to ground a simulated agent in a real researcher’s profile but do not need the full to_dict() payload at seeding time. Includes only identity fields plus the full expertise/soul markdown bodies and a paper count.

to_dict(include_summaries: bool = False)

Return a JSON-serializable dict representation.

By default summary_ids (only the keys) is included to keep payloads small. Pass include_summaries=True to substitute summaries: {id: text} with the full bodies.

validate()

Validate this profile directory against the on-disk format schemas.

Returns a researcher_profiles.validate.ProfileValidationReport, which carries an ok property, the per-artifact results, and the violations behind them.

write_unit(kind: str)

The transactional boundary for one logical write.

A one-line delegation to researcher_profiles.profile.write_unit.WriteUnit.open, which owns the ordering and failure contracts. This stays a real method because api.deps and the guardrail suite monkeypatch it.

Owner edits

class EditManager(profile: ResearcherProfile)

Owner-edit policy and mutation surface for one profile.

Methods

patch_metadata(patch: dict[str, Any])

Patch owner-editable metadata fields and persist the document.

set_soul(soul: str)

Replace the free-form SOUL/persona narrative.

set_visibility(profile_visibility: str | None = None, artifacts: list[dict[str, Any]] | None = None)

Set the profile-level and per-artifact privacy tiers.

Exceptions

class ProfileError

Base exception for researcher_profiles.

class ProfileLoadError(location: Any, message: str, original: Exception | None = None)

Raised when a stored profile artifact is malformed or unreadable.

location is untyped, mirroring ProfileWriteError: the filesystem backend passes a Path, a static host passes a URL, a database backend passes a table/row reference.

Properties

location

original

class ProfileWriteError(location: Any, message: str, original: Exception | None = None)

Raised when a profile artifact cannot be persisted, or when the backing store is read-only.

Mirrors ProfileLoadError’s signature, but location is untyped: the filesystem backend passes a Path, a static host passes a URL, a database backend passes a table/row reference.

Properties

location

original

class CapabilityUnavailableError

A capability needs something this backend does not have.

both a ProfileError and a NotImplementedError, for the same reason ProfileNotFoundError is both a ProfileError and a KeyError: existing callers catch NotImplementedError, while a management host wants to catch it with the package’s other errors.

class ProfileValidationError(report: Any)

Raised when from_files(..., validate=True) produces a non-ok report.

Properties

report

class PersonaUnavailableError(slug: str)

Raised when a persona method is called on a profile with no persona.

The persona endpoints (.ask/.review/.innovate/.riff) require a fully-synthesized profile: both expertise.md and SOUL.md must be present and non-empty (see ResearcherProfile.has_persona). An incomplete / “lite” profile is a client-visible precondition failure, not a server error, and must not silently role-play an empty persona. Subclasses ProfileError so library callers can catch either this or the base.

Properties

slug

---

Export for knowledge bases

researcher_profiles.profile.export turns one profile into a single block of prose plus the metadata that travels with it, so a connector pushing profiles into a knowledge base (KB) never has to open profile.jsonld, expertise.md, SOUL.md and papers.jsonld itself, re-implement the privacy rule, or invent a change detector. The idempotency contract behind content_hash is explained in docs-dev/rp-sdk/explanation/sdk-architecture.md.

Entry points

render_export_text(profile: ResearcherProfile, options: ExportOptions | None = None, papers: Sequence[PaperRecord] | None = None)

Render one profile as a single deterministic markdown blob.

The blob is the whole payload a knowledge base ingests: a synthesized narrative (identity, expertise, interests, career, then the expertise.md and SOUL.md bodies verbatim) followed by the prose of a selected, topic-representative set of papers. How it is chunked and embedded is entirely the consumer’s business.

Deterministic by contract. There is no timestamp, counter, hash, or host-dependent value anywhere in the output: two renders of an unchanged directory are byte-identical. ProfileExportBundle.content_hash depends on that.

Pass papers to skip selection entirely. That is the override for a caller that has embeddings and can choose better than this module can.

Raises ExportVisibilityError when the profile document’s visibility is above public and options.allow_nonpublic is not set.

select_export_papers(profile: ResearcherProfile, options: ExportOptions | None = None)

The topic-representative subset of a profile’s papers, deterministically.

Filter (untitled, contaminated, bodyless, non-public), score (authorship + impact + recency), then diversify greedily so the selection spans the researcher’s topics instead of stacking their most-cited cluster. No embeddings are involved. A caller that has vectors should select its own list and pass it to render_export_text instead.

Returned in presentation order (year desc, then title), which is not selection order.

build_export_bundle(profile: ResearcherProfile, options: ExportOptions | None = None, papers: Sequence[PaperRecord] | None = None, now: str | None = None)

Render a profile and wrap it with the metadata a knowledge base needs.

The returned bundle is the whole handoff: a connector maps its fields onto the destination’s document schema, upserts keyed on rid, and uses content_hash as the change detector. Re-running a backfill is then a no-op, which is what makes a first load and a later refresh the same operation.

explore_url(profile_url: str | None, explore_base: str | None = None)

The browser-app backlink for a published profile directory.

Returns None unless both a profile URL and an explore base are given. The hash shape matches what the browser app parses back to the same directory: a trailing slash, profile.jsonld stripped, percent-encoded.

export_content_hash(payload: Mapping[str, Any])

"sha256:<64 hex>" over payload in canonical JSON form.

jsonld.canonical_dumps fixes key order and formatting, so the digest is reproducible across machines and Python versions rather than depending on dict insertion order.

export_paper_body(profile: ResearcherProfile, paper: PaperRecord, options: ExportOptions | None = None)

Return (text, source) for one paper’s prose.

source is "summary" or "abstract". The summary body is the markdown after any YAML frontmatter fence (whose shape is schema.SummaryFile), with the [abstract-only] bookkeeping marker removed and whitespace normalized. Returns ("", "abstract") when the paper has no usable body at all.

ExportOptions

class ExportOptions

Every knob the export surface has.

Options live on this model rather than in positional parameters so a downstream connector never breaks on a signature change: a new knob is a new field with a default, and existing callers keep working untouched.

Properties

allow_nonpublic: bool = False : Permit export of a profile whose document visibility is above public.

char_budget: int | None = 120000 : Soft cap on total blob characters. Whole paper blocks are dropped from the end; a body is never truncated mid-text. None disables it.

diversity: float = 0.7 : Overlap-penalty weight in the greedy paper selector (0..1).

explore_base: str | None = None : Base URL of a profile browser app. When unset, the bundle carries no explore_url.

include_expertise_doc: bool = True : Include personality/expertise.md.

include_soul: bool = True : Include personality/SOUL.md.

max_papers: int = 40 : Cap on papers whose text enters the blob.

prefer_summaries: bool = True : Use a paper’s sources/summaries/.summary.md body when present, falling back to its abstract.

profile_url: str | None = None : Override for the published profile URL (default: metadata.url).

ProfileExportBundle

class ExportPaperRef

One paper whose prose is inside the rendered text.

Properties

body_source: Literal[‘summary’, ‘abstract’]

doi: str | None : Normalized and bare (10.xxxx/yyy), never a resolver URL.

paper_id: str | None

title: str

year: int | None

class ProfileExportBundle

One profile, rendered for a knowledge base: the text plus what travels with it.

dois and papers are different things and must not be conflated. dois is the profile’s full corpus DOI list: every paper in sources/papers.jsonld, normalized and de-duplicated, in document order. A KB uses it to link this profile to works it already holds, whether or not their prose is in this export. papers is the much smaller subset whose prose is actually inside text.

content_hash is the idempotency key. It covers every field except itself and built_at (including summary, which is real content, so an edited summary triggers a refresh), hence two builds seconds apart hash identically and a KB upserts only when the hash changes.

Properties

affiliation: str | None

built_at: str

conforms_to: str

content_hash: str

dois: list[str]

explore_url: str | None

export_version: int

field: str | None

level: str

license: str | None

name: str

orcid: str | None

paper_count: int

papers: list[ExportPaperRef]

profile_url: str | None

provenance: str

rid: str

sdk_version: str

slug: str

summary: str | None : The profile’s one-paragraph self-description (metadata.summary), the same value rendered into the blob’s ## Overview. Carried as its own field so a connector can use it as a short document description without re-opening profile.jsonld. This package owns profile reading.

text: str

text_chars: int

visibility: str

Exceptions

class ExportError

Base error for the knowledge-base export surface.

class ExportVisibilityError

The profile is not public and the caller did not opt in.

Pass allow_nonpublic=True (CLI: --allow-nonpublic) when the destination is authorized to hold the profile’s tier.

---

Cross-profile analytics (store.match, store.centroids, store.indexes)

There is no aggregate object over a store: a collection of profiles is the store. The three cross-profile concerns hang off it as accessors, the same way prof.cite hangs off a profile. They require the [vectors,st] extras (they need numpy) and are imported on first access, so a core-only install still uses the store for everything else.

Ranking and centroids also need the VectorStore capability; a store without it raises CapabilityUnavailableError naming what to do instead.

class DuplicateIdentityError

Two profiles in one store claim the same rid.

A store is the only place this can be detected, because it is the only place that sees every profile at once. The filesystem backend is the only one that can hit it: SQL makes it structurally impossible (rid is the primary key) and a published site’s by-rid.json is a mapping that cannot hold two entries under one key.

store.centroids (centroids and the query backend)

class CentroidManager(store: VectorStore, rostered: _RosterCache)

store.centroids, the centroid matrix and the query embedder.

Both live here because they must agree: a query vector is only comparable to the matrix when it came out of the same backend the indexes were built with.

Properties

backend : The backend queries are embedded with, resolved once and kept.

cache_path: Optional[Path] : <root>/.cache/centroids.npz, or None without a root.

matrix: np.ndarray : L2-normalized centroids, one row per profile, slug-ordered.

Methods

embed_query(text: str)

text as a unit vector in the same space as matrix.

invalidate()

Drop the in-memory matrix and unlink the .npz.

snapshot()

(roster, matrix), guaranteed row-aligned.

The pair, not the matrix alone, is what ranking needs: row i of the matrix is roster.slugs[i] for as long as the caller holds both. A caller that fetched the roster and the matrix in two steps could be handed a matrix rebuilt across a write in between, and would then read every score off the wrong profile.

store.match (ranking and analysis)

class MatchManager(store: VectorStore, rostered: _RosterCache)

store.match: ranking, diversification, topics, clustering.

Properties

topics_cache_path: Optional[Path] : <root>/.cache/topics.json, or None without a root.

Methods

cluster(k: int | None = None)

Group profiles by centroid; each group is named for its exemplar.

diversify(matches: list[Match], k: int = 5, lambda_: float = 0.5)

Re-order by maximal marginal relevance: relevant but not redundant.

invalidate()

Unlink the topics view.

rank(text: str, k: int = 5, prefilter: int = 10, normalize: bool = True, require_topics: list[str] | None = None, diversify: bool = True, lambda_: float = 0.5, topk_chunks: int = 5)

Rank every profile in the store against a free-text query.

topics()

Topic label -> the profiles claiming it. Also written to disk.

store.indexes (embedding-index maintenance)

The object is analytics.IndexFleetManager, distinct from the per-profile profile.index.IndexManager that prof.index hands back.

class IndexFleetManager(store: ProfileStore, rostered: _RosterCache)

store.indexes: build and report on every profile’s index.

Methods

coverage()

Per-profile index / topic / calibration status, slug-ordered.

The rendered form of stats plus the two derived caches that do not live in the index file.

rebuild_all(force: bool = False)

Rebuild every profile’s index, then drop everything derived from it.

Fail-soft per profile: one broken profile is reported as None and does not stop the rest.

stats()

slug -> IndexStats, one index open per profile.

---

ApiArtifactStorage and StaticArtifactStorage

researcher_profiles.client provides the two HTTP backends. It requires the [client] extra. Neither is a profile: build an ordinary ResearcherProfile over one with ResearcherProfile.from_api(url) or .from_url(url), and it behaves like a local profile, with the same properties and method signatures.

class ApiArtifactStorage(slug: str, base_url: str, token: Optional[str] = None, timeout: float = 60.0, client: Any = None)

A profile served by a live researcher_profiles.api server.

Read-only: every writer is refused by ReadOnlyArtifactStorage. Reads come off the combined detail payload where the API has one, and off the dedicated routes otherwise.

Properties

base_url

directory: None

key: str

rid_hint: None

slug: str

Methods

artifact_bytes(content_url: str)

artifact_text(content_url: str)

Only what v1 serves: soul, expertise, and paper summaries.

Returns None otherwise. An invented empty body is worse than an empty column, and the v1 API has no route that hands back an arbitrary artifact’s bytes.

build_manifest()

The manifest the served document records; there is nothing to walk.

close()

collection_envelope(content_url: str)

content_hash()

"sha256:<hex>" over the served document + soul.

A read, so it stays supported on a read-only view. Computed from the combined detail payload rather than raw bytes, because the API serves a document, not a file.

index(profile: ResearcherProfile)

search over HTTP; everything else needs the local sqlite handle.

load_citations()

load_document()

load_expertise()

load_grants()

load_papers()

load_soul()

load_summaries()

locate(parts: str = ())

Display-only locator: the API URL naming this artifact.

persona(profile: ResearcherProfile)

HTTP-backed persona: the server owns model, corpus and refusals.

refresh()

Drop cached immutable resources so the next access refetches.

class StaticArtifactStorage(url: str, timeout: float = 30.0, client: Any = None)

A published profile directory on a dumb static host (Pages, S3, …).

Unlike ApiArtifactStorage (which talks to a live researcher_profiles.api server), this fetches the published files themselves (profile.jsonld, personality/*.md, sources/*.jsonld) with one lazy GET per artifact. Summaries are enumerated from the manifest in profile.jsonld, since a static host has no directory listing.

persona and index are not overridden: the local managers are built, and the index’s require_directory refuses with the install_profile() message.

Properties

base_url

directory: None

key: str

rid_hint: None

slug: str

Methods

artifact_bytes(content_url: str)

artifact_text(content_url: str)

Whatever the host serves at that relative path.

A published static directory is the manifest’s address space, so any contentUrl is fetchable, subject to the host’s own access rules, which surface as PermissionError.

build_manifest()

The recorded manifest: a static host has no directory to walk.

close()

collection_envelope(content_url: str)

content_hash()

"sha256:<hex>" over the fetched document + soul.

A read, so it stays supported on a read-only view.

load_citations()

load_document()

load_expertise()

load_grants()

load_papers()

load_soul()

load_summaries()

locate(parts: str = ())

Display-only locator: the published URL naming this artifact.

rank_against (module-level)

rank_against(base_url: str, query: str, k: int = 5, token: Optional[str] = None, prefilter: int = 10, require_topics: Optional[list[str]] = None, diversify: bool = True, lambda_: float = 0.5, topk_chunks: int = 5, normalize: bool = True, include_chunks: bool = False, timeout: float = 60.0, client: Any = None)

Rank indexed profiles on a remote server against query.

Registry ranking is not profile-scoped, so this is a module-level function (not an ApiArtifactStorage method). POSTs to /api/v1/match and returns the parsed matches list (plain dicts shaped like MatchResult: {slug, name, orcid, score, evidence{...}}).

resolve_rid (module-level)

resolve_rid(base_url: str, rid: Optional[str] = None, name: Optional[str] = None, affiliation: Optional[str] = None, create_new: bool = False, token: Optional[str] = None, timeout: float = 30.0, client: Any = None)

Resolve a person descriptor to a rid against the identity authority.

The consumer-side half of POST /api/v1/identity/resolve: a service holding a free-text name or a bare ORCID calls this at its boundary and stores the returned rid (as a scholarcore PersonRef), instead of hand-rolling HTTP or minting its own local id, which is worse. Resolution is authoritative and idempotent server-side: the same person resolved from two services gets the same rid.

rid is an ORCID or a local: id the resolver minted. token must carry the resolve scope (falls back to the RESEARCHER_PROFILES_TOKEN env var). A rid of None on the result means the name was undecidable. Inspect candidates and re-call with the chosen profile’s rid, or with create_new=True when none of the candidates is your person (the server mints a fresh identity; never guess between candidates).

---

OpenAlex parser

researcher_profiles.openalex does pure record parsing, with no HTTP. It is available in core.

parse_work(raw: dict)

Parse a raw OpenAlex work dict into a PaperRecord.

Extracts the fields a profile needs: title/year (with a guard), first-author last name, journal (primary_location then host_venue), preferred pdf_url, bare doi, pmid (from ids), pmcid (from locations), cited_by_count, lowercased type, and the de-inverted abstract.

This function does not compute paper_id. That is ID policy, not OpenAlex parsing, so paper_id is left None for the caller to fill. cited_by_count, pmid and pmcid are carried as extra fields (PaperRecord allows extras).

Returns: A PaperRecord (status="pending"), or None when the work has no title or no publication year (not usable).

decode_abstract_inverted_index(idx: dict[str, list[int]] | None)

Reconstruct an abstract string from an OpenAlex abstract_inverted_index.

The OpenAlex inverted index format maps each word to the list of positions (0-based) where that word appears in the abstract:

{"Despite": [0], "decades": [1], "of": [2, 20, 38], ...}

Algorithm:

1. If idx is None or empty -> return "" (no exception raised).
2. Build a flat list of (position, word) pairs from all entries.
3. Sort by position ascending.
4. Detect duplicate positions: if two words claim the same position, log a warning and keep the first occurrence (stable-sort order).
5. Detect gaps: if positions are not contiguous from 0 to max(pos), fill each missing position with a single space (log at DEBUG level).
6. Join the resolved words with single spaces.
7. Strip leading/trailing whitespace; collapse repeated internal whitespace.

Returns: The reconstructed abstract string, or "" on any structural failure.

to_work_dict(raw: dict)

The {title, abstract, year, doi, openalex_id, coauthors} lite shape.

doi is the bare DOI (no https://doi.org/ prefix). abstract is None (not "") when absent. This adapter maps the empty de-inversion result to None so an absent abstract is distinguishable from an empty one.

to_normalized_dict(raw: dict)

The single-work-match shape: identical to to_work_dict but with authors in place of coauthors (the citation checker keys off author names).

---

Embeddings store

researcher_profiles.embeddings is a per-profile vector store. It requires the [vectors,st] extras.

class SqliteEmbeddingIndex(profile_dir: str | os.PathLike, profile_document: Any = None)

sqlite-vec index for a single profile.

Properties

SCHEMA_VERSION

backend_spec: str : The embedding model this index was built with; "" when unbuilt.

db_path

index_dir

profile_dir

Methods

build_index(force: bool = False, backend: EmbeddingBackend | str | None = None)

centroid()

The L2-normalized mean of every chunk vector, npz-cached.

The other half of VectorIndex. Delegates to index_centroid, which is also what prof.index.embedding("centroid") reaches, so a centroid read through a store and one read through a profile are the same number out of the same cache. Imported inside the method: numpy is the vectors extra and the facts-about-the-file half of this class stays usable without it.

counts()

(n_chunks, n_papers).

Papers counts DISTINCT source_id over PAPER_CHUNK_TYPES, so a lite profile’s abstracts count as papers.

exists()

True when embeddings.sqlite is present.

index_meta()

index_meta as a dict; {} when there is no readable index.

mtime()

The index file’s mtime, or None when it is absent.

search(query: str, k: int = 5, filter: dict | None = None)

search_similar(source_type: str, source_id: str, chunk_index: int = 0, k: int = 5)

stats()

exists + counts + index_meta + mtime.

build_index(profile, force: bool = False, backend = None)

Build (or refresh) the embedding index for a profile.

profile may be either a ResearcherProfile or a path-like pointing at a profile directory. The function is the thin, importable entry point used by the create/update pipeline; the heavy lifting lives on SqliteEmbeddingIndex.

researcher_profiles.profile.index.IndexManager is what prof.index hands back: build, search, search_similar, embedding. Distinct from analytics.IndexFleetManager (above), which operates over every profile in a root rather than one profile’s own index.

class IndexManager(profile)

prof.index: the per-profile embedding index.

Needs a directory: .cache/embeddings.sqlite is a sqlite handle and the derived caches are not covered by ArtifactStorage. The check lives here, once, instead of in three subclass overrides.

Methods

build(force: bool = False, backend = None)

Build (or refresh) this profile’s embedding index.

embedding(kind: str = 'centroid')

The profile-level vector: centroid / summary / expertise.

search(query: str, k: int = 5, filter: dict | None = None)

Semantic search over this profile’s chunks.

search_similar(source_type: str, source_id: str, chunk_index: int = 0, k: int = 5)

Chunks nearest to one this profile already holds.

class SearchHit(text: str, source_type: str, source_id: str, chunk_index: int, section: str | None, cosine: float, score: float, meta: dict = dict())

Properties

chunk_index: int

cosine: float

meta: dict

score: float

section: str | None

source_id: str

source_type: str

text: str

Methods

to_dict()

class IndexReport(added: int = 0, updated: int = 0, skipped: int = 0, removed: int = 0, backend_name: str = '', duration_s: float = 0.0)

Properties

added: int

backend_name: str

duration_s: float

removed: int

skipped: int

updated: int

Methods

to_dict()

Exceptions

class MissingEmbeddingBackendError

Raised when the chosen embedding backend is not importable / usable.

class IndexBackendMismatchError

Raised when the existing index was built with a different backend.

Pass force=True to drop and recreate.

class IndexNotBuiltError

Raised when an index is read but none exists yet at that path.

---

Result dataclasses

researcher_profiles.models.results holds the return types for capability methods.

class PersonaResponse(text: str, citations: list[CitationRef], model: str, usage: dict, raw: Any, request_id: Optional[str] = None, refused: bool = False, refusal_reason: Optional[str] = None, grounded: bool = True)

What every persona method returns: .ask, .review, Chat.send.

One shape, because the three answer the same kind of question: a piece of text written in the researcher’s voice, plus the papers it leaned on and the accounting for the call that produced it.

grounded is False when the model cited a paper_id that is not in this profile’s paper set: the answer may still be useful, but it left the corpus. refused is True when strict-corpus retrieval came back too weak to answer from and the persona declined rather than improvised; refusal_reason then carries the retrieval score and threshold. A refusal is a successful call, not an error.

raw is the provider’s own response object, for callers that need something this dataclass does not expose. It is local-only: the HTTP API never serializes it, so a response that arrived over the wire has raw=None.

Properties

citations: list[CitationRef]

grounded: bool

model: str

raw: Any

refusal_reason: Optional[str]

refused: bool

request_id: Optional[str]

text: str

usage: dict

class Idea(hypothesis: str, approach: str, rationale: str, related_works: list[str])

One proposed research direction from ResearcherProfile.innovate.

Properties

approach: str

hypothesis: str

rationale: str

related_works: list[str]

Methods

resolve_citations(profile)

Map related_works citation keys to paper records (or None).

Returns a mapping {citation_key: PaperRecord | None}. Unknown keys map to None rather than raising.

class Riff(angle: str, text: str, related_work: Optional[str] = None)

One brainstorm fragment from ResearcherProfile.riff.

Properties

angle: str

related_work: Optional[str]

text: str

class CitationRef(paper_id: str, relevance: float | None = None, span: str | None = None)

A lightweight reference to a paper used as evidence for a response.

Properties

paper_id: str

relevance: float | None

span: str | None

Methods

to_dict()

class Citation(paper_id: str, title: str, authors: list[str] = list(), year: int | None = None, venue: str | None = None, doi: str | None = None, url: str | None = None, pdf_url: str | None = None, abstract: str | None = None)

A fully-expanded citation record for a single paper.

Properties

abstract: str | None

authors: list[str]

doi: str | None

paper_id: str

pdf_url: str | None

title: str

url: str | None

venue: str | None

year: int | None

Methods

to_bibtex()

to_csl()

to_dict()

class Match(profile: Any, score: float, evidence: MatchEvidence, explanation: Optional[str] = None)

One profile match against a query, with score, evidence, and lazy explanation.

Properties

evidence: MatchEvidence

explanation: Optional[str]

profile: Any

score: float

Methods

explain(query: str = '', client: Any = None)

Produce a short LLM-backed explanation of why this profile matched.

Cached on first call. Subsequent calls return the cached value.

to_dict()

class MatchEvidence(top_chunks: list[Any], top_papers: list[str], overlapping_topics: list[str], centroid_score: float)

Evidence supporting a profile match for a query.

Properties

centroid_score: float

overlapping_topics: list[str]

top_chunks: list[Any]

top_papers: list[str]

Methods

to_dict()

class Topic(label: str, weight: float, paper_ids: list[str] = list(), chunk_ids: list[int] = list())

A topic cluster extracted from a profile’s chunk embeddings.

Properties

chunk_ids: list[int]

label: str

paper_ids: list[str]

weight: float

Methods

to_dict()

class Coverage(name: str, affiliation: str | None, one_liner: str | None, topics: list[str], expertise_summary: str, year_range: Optional[tuple[int, int]], paper_count: int, last_updated: datetime, staleness_label: str, suggested_questions: list[str], coverage_caveats: list[str])

Landing-page metadata: what a profile covers and how fresh it is.

Properties

affiliation: str | None

coverage_caveats: list[str]

expertise_summary: str

last_updated: datetime

name: str

one_liner: str | None

paper_count: int

staleness_label: str

suggested_questions: list[str]

topics: list[str]

year_range: Optional[tuple[int, int]]

Methods

to_dict()

class GenerativeParseError(message: str, raw_text: str = '')

Raised when the LLM repeatedly fails to return valid JSON.

Properties

raw_text

PersonaUnavailableError is documented under ResearcherProfile exceptions above.

---

ProfileStore (researcher_profiles.store)

The collection-level interface: a set of profiles. Each profile’s artifacts live one level down in ArtifactStorage. It is what an HTTP app, an ingest path, or a management host is handed, and it is what create_app takes. The “one filesystem admission” (store.root) is explained in docs-dev/rp-sdk/explanation/sdk-architecture.md.

class ProfileStore

A set of profiles, whatever they are stored in.

Every method takes ref: a slug or a rid. Resolution is the store’s job, not the caller’s. An HTTP route that had to know which namespace it was handed would be re-implementing resolve_slug at every entry point.

Properties

location: str : A human-readable locator for this store. Display only.

root: Optional[Path] : The filesystem root when this store is a directory, else None.

Methods

add_post_commit_hook(hook: WriteHook)

Register a callable to run after a write commits successfully.

Same reach as add_pre_commit_hook. The difference is what the hook may do: a pre-commit hook can still abort the write by raising; a post-commit hook cannot, because the write already landed. Use this for fire-and-forget notifications to something outside the store (for example, pushing to an external search index). See researcher_profiles.profile.ResearcherProfile.add_post_commit_hook.

add_pre_commit_hook(hook: WriteHook)

Register a callable to run inside every write, before commit.

Registration belongs here, on the store, and not on an HTTP app: a hook registered on an app fires only for writes that went through a route that remembered to fire it, so a background writer that bypasses the routes would skip it. Applies to profiles handed out from now on and to any already handed out, so registration order relative to a first get does not matter.

artifact_bytes(ref: str, content_url: str)

One manifest artifact’s bytes, addressed by its contentUrl.

Raises ProfileNotFoundError when the profile or the artifact is absent. Applies no privacy policy: the caller has already decided who may read this (see api.routers.read.get_profile_artifact).

commit_directory(slug: str, staging: Path, build_missing_index: bool = False)

Make a fully-staged profile directory live in this store.

staging is a complete profile directory (profile.jsonld at its root). The directory is the interchange format, not the storage format: a tarball push, a URL import and rp db push all speak it. Each backend decides what “live” means: an atomic rename for the filesystem, a transaction for SQL.

build_missing_index asks for a best-effort embedding-index build afterwards, for a host that wants an ingested profile immediately rankable. A backend with no filesystem accepts it and ignores it.

Raises UploadError if the staged directory does not load.

content_hash(ref: str)

"sha256:<hex>" over the canonical document and the SOUL text.

Store-maintained derived state, refreshed inside the write unit before the pre-commit hooks run, so a hook reading it observes post-write content. Identical across backends by construction; see researcher_profiles.store.db.content_hash_for.

create(document: ProfileDocument, slug: str)

Create a new profile from a validated document. Returns it.

Runs in one write unit of kind "create", so a management host’s pre-commit hook can write its ownership row in the same transaction. That closes the orphan-profile window between “the profile exists” and “somebody owns it”.

Raises ProfileWriteError if slug or the document’s rid is already taken.

delete(ref: str)

Remove a profile and everything belonging to it. Returns its rid.

document_bytes(ref: str)

The canonical profile.jsonld bytes, exactly as persisted.

What a crawler fetching /profiles/{slug}/profile.jsonld receives has to be the published document, byte for byte, or the conformsTo claim is about a file nobody can retrieve.

evict(ref: str)

Drop any cached view of ref so the next get reloads.

A no-op on a store that does not cache. Cache invalidation only: dependent-state maintenance belongs on add_pre_commit_hook, where it runs inside the write instead of after it.

exists(ref: str)

Whether ref names a profile in this store.

export_directory(ref: str, dest: Path)

Materialize a profile as a directory at dest. Returns dest.

The inverse of commit_directory, and the way out of any store for the capabilities that need a real directory (validation, the embedding index).

get(ref: str)

Load a profile. Raises ProfileNotFoundError.

The returned profile carries every hook registered through add_pre_commit_hook, so a write through it fires them whether it came from an HTTP route, the CLI, or an out-of-process pipeline run.

list_slugs()

Every profile’s display handle, sorted.

put_document(slug: str, document: ProfileDocument)

Create-or-replace a profile’s canonical profile.jsonld.

Runs in one write unit (kind "create" if new, "edit" if it exists), so hooks fire and dateModified is stamped. Derived artifacts (sources/, .cache/) are left untouched: this writes the document, not the bundle.

This is the JSON upsert path: what PUT /api/v1/profiles/{slug} dispatches to when the request body is application/json rather than a tarball. It writes identity + expertise + metadata; enrichment (papers, embeddings) is added later by a push or a build.

Returns the profile, so the caller can read rid / name / level for the response.

resolve_slug(ref: str)

Map a slug or a rid to the slug. Raises ProfileNotFoundError.

rid_for(ref: str)

Map a slug or a rid to the rid. Raises ProfileNotFoundError.

The mirror of resolve_slug. Both exist because the two are used for different things: rid is the identity every cross-system mapping joins on; slug is what a URL and a human say. A bare ORCID resolves here too, because an ORCID rid is its ORCID (scholarcore.identity.orcid_of derives one from the other and invents nothing).

write_lookup_index()

Persist rid <-> slug so shell callers resolve without importing.

A shell caller resolving a rid to a directory reads this file, which is what lets a rid work anywhere a slug does regardless of directory name. Nothing writes it implicitly: a caller that owns a writable root calls this when it wants the file fresh. Returns None on a store with no directory to write into, which is not a degradation: such a store answers the same question in process through rid_for.

class FilesystemProfileStore(root: str | os.PathLike, capacity: int = 32)

Profiles as directories under one root, with a small LRU over the loaded ResearcherProfile objects.

Eviction is a no-op beyond dropping the reference. The sqlite handles are GC’d along with the index objects on the profile.

Properties

backend_spec: str | None : The first readable backend name across the root, sqlite or flat.

capacity

location: str

root: Path : The profiles root. This backend is a directory, so never None.

Methods

artifact_bytes(ref: str, content_url: str)

Read one artifact, refusing anything that escapes the profile dir.

The traversal check is here rather than at the call site, so every caller inherits it. A store that can be talked into reading ../../etc/passwd has a bug in the store, not in one route.

centroid(ref: str)

The profile’s centroid, from whichever index vector_index picked.

centroids_matrix()

None: a directory holds no stacked matrix, only per-profile vectors.

<root>/.cache/centroids.npz is not it. That file is the memo store.centroids keeps of its own computed matrix; returning it here would make the manager read its own cache back through the store and call the result authoritative.

commit_directory(slug: str, staging: Path, build_missing_index: bool = False)

Validate a staged directory loads, then atomically swap it live.

build_missing_index is off by default because the operator push (PUT /api/v1/profiles/{slug}) ships its own index and a rebuild there is wasted minutes; a host ingesting on a person’s behalf, who wants their profile rankable immediately, turns it on. When it is on and .cache/embeddings.sqlite is absent, a best-effort build runs afterwards: a core-only install or a build failure leaves the profile committed but unindexed rather than raising. The profile is hosted, but not yet in /match.

content_hash(ref: str)

Recomputed per call: this backend stores no digest column.

Same two-artifact, NUL-separated surface every backend reports; see researcher_profiles.profile.ResearcherProfile.content_hash.

create(document: ProfileDocument, slug: str)

Create <root>/<slug>/ and persist document into it.

One write unit of kind "create", so a host’s pre-commit hook lands its own state in the same logical write. On the filesystem that unit is not atomic (ctx.atomic is False). A raising hook leaves the directory behind, which is why this backend removes it explicitly rather than pretending a rename undid anything.

delete(ref: str)

document_bytes(ref: str)

evict(ref: str)

Drop a cached profile so the next get reloads from disk.

Bumps the write generation too. evict is what the API layer calls after every write, including one that arrived by a path this store never saw (an extracted archive swapped in over its directory), so treating it as “something changed” is what keeps the analytics honest without making that caller import them.

exists(ref: str)

export_directory(ref: str, dest: Path)

Copy a profile directory to dest. Build state is not copied.

The build root is a sibling tree outside the content root, so a copy of the content directory is the published record and nothing else. That is the same thing SqlProfileStore.export_directory produces without with_build.

get(ref: str)

has_vector_index(ref: str)

Whether the profile ships either vector form. Two stats, no parsing.

list_slugs()

path_for(ref: str)

The absolute profile directory for a slug or a rid.

Numpy-free, which is the point: rp where is a path lookup and used to import the whole vector stack to do it.

put_document(slug: str, document: ProfileDocument)

Create-or-replace a profile’s canonical document only.

If the profile exists, runs an "edit" write unit; if new, runs a "create" unit so a host’s pre-commit hook can write ownership. The write uses the profile’s save_profile so dateModified is stamped correctly and hooks fire.

resolve_slug(ref: str)

Map a profile reference to a directory name.

ref is either the directory name itself or a rid (a canonical ORCID or a local: id). Directory-first, because that is the common case and a directory name can never be mistaken for a rid.

rid_for(ref: str)

Map a slug or a rid to the rid. Raises ProfileNotFoundError.

A bare ORCID resolves here without any extra indexing: an ORCID rid is its ORCID (scholarcore.identity.orcid_of derives one from the other and invents nothing), so it is already a key of the rid map.

vector_index(ref: str)

The profile’s vectors: the build-local sqlite, else the served flat form.

sqlite first because it is the richer index: it carries every chunk, including the restricted ones the public export drops, and its hits carry text. A directory that only holds a published profile (no .cache/) still ranks, at the public subset, through the flat form.

The imports are inside the method. This module is on the core import path and both readers pull numpy.

write_lookup_index()

Persist rid <-> slug into <root>/.cache/index.json.

A shell caller resolving a rid to a directory reads this, which is what lets a rid work anywhere a slug does, regardless of directory name. Nothing writes it implicitly: a caller that owns a writable root calls this when it wants the file fresh.

class SqlProfileStore(engine_or_url: Any)

A set of profiles living in SQL tables.

engine_or_url may be a SQLAlchemy Engine or a connection URL. The store owns no per-profile state: every operation opens its own session, and the SqlArtifactStorage behind a profile handed out by get opens its own for each read and each write unit.

An in-memory SQLite URL (sqlite:// / sqlite:///:memory:) gets StaticPool: an in-memory database is private per connection, and the default per-thread pool would let this store and the threadpool serving HTTP requests over it silently see two different empty databases. StaticPool keeps the one connection that holds the data.

Properties

backend_spec: str | None : The embedding space this store’s vectors live in, or None.

engine

location: str : The database URL. Display only.

root: None : Always None: this store is not a directory.

url

Methods

artifact_bytes(ref: str, content_url: str)

One manifest artifact’s bytes.

There is no traversal check because there is no path: content_url is a key in rp_artifacts, and a key that is not there is a 404 rather than a walk up the filesystem. A rendered collection is regenerated from rp_papers / rp_grants on the way out, exactly as it is for export_directory.

centroid(ref: str)

The profile’s stored centroid: one row, already normalized.

Not derived from vector_index. The centroid is computed at ingest over the whole index, restricted chunks included (one averaged vector is not invertible, spec section 6), exactly as the published collection/embeddings/ blob is, while the chunk rows are the public subset. Recomputing it from the chunk rows would quietly answer a different question.

centroids_matrix()

The whole roster’s centroids in one SELECT, or None.

This is the payoff of storing profile vectors in their own table: ranking N profiles costs one query rather than N index reads, the same way a published site’s single stacked blob costs one fetch.

commit_directory(slug: str, staging: Path, build_missing_index: bool = False)

Make a fully-staged profile directory live in this store.

One transaction, which is what replaces the filesystem backend’s rename-aside-and-swap: there is no window in which the profile half exists, so a host’s pre-commit hook granting ownership commits with it or not at all.

When the staged profile carries a built embedding index (.cache/embeddings.sqlite), its public chunks are shredded into rp_chunk_vectors and its centroid into rp_profile_vectors, and indexed=True is reported; /match then queries those rows directly, with no directory and no runtime embedding backend needed to serve them.

build_missing_index builds one in the staging directory first, exactly as the filesystem backend does and for the same reason: ingest is now the only moment a vector can enter this store, so a profile staged without an index would otherwise be hosted and permanently unrankable. Best-effort: a core-only install or a build failure leaves the profile committed but unindexed, never unhosted.

content_hash(ref: str)

The stored content_hash column: derived state, not a recompute.

Refreshed inside the write unit before the pre-commit hooks run, so a hook reading it observes post-write content. Spans the canonical document and the SOUL text, NUL-separated, identically to every other backend.

create(document: ProfileDocument, slug: str)

Create a new profile from a validated document, in one write unit.

The row is inserted bare and then written through ResearcherProfile.save_profile, so the create takes exactly the same validate -> stamp -> canonicalize -> persist path every other write takes. A management host’s pre-commit hook therefore sees kind="create" with a live session and can write its ownership row in the same transaction, closing the window where a profile exists that nobody owns.

create_all()

Create the rp_* tables if absent. Fresh-instance convenience.

delete(ref: str)

Remove a profile and every child row, including its build state.

document_bytes(ref: str)

The canonical profile.jsonld bytes for ref.

Serialized on demand from the stored document rather than kept in a second document_bytes column. researcher_profiles.schema.jsonld.canonical_dumps is the package’s only writer of .jsonld bytes and is a pure function of the mapping (one fixed key order, one fixed formatting), so these bytes are the bytes save_profile persisted and export_directory writes. A byte column would be a second representation of the same fact, and two representations of one fact drift.

evict(ref: str)

Bump the write generation. There are no cached rows to drop.

This store caches nothing of its own, but evict is the protocol’s “drop any view that could still be pre-write”, and the analytics on this store hold exactly such a view. The API layer calls it after every write, so bumping here is what keeps /match current without that caller importing anything vector-shaped.

exists(ref: str)

export_directory(ref: str, dest: str | Path, with_build: bool = False)

Materialize a stored profile as a directory. Returns the directory.

profile.jsonld is canonical_dumps(document); every artifact body is written to its own contentUrl; the works and grants collections are re-rendered from rp_papers / rp_grants inside their stored envelope, so the collection metadata (about, dateModified, @context) survives the round trip.

Vectors are written as the published flat form (embeddings/index.json + <backend>.bin + <backend>.chunks.json) regenerated from rp_chunk_vectors, after the artifact bodies and overwriting whatever they wrote, so the declared count and sha256 always describe the blob beside them. No .cache/embeddings.sqlite is reconstituted: nothing needs one, since the filesystem backend reads the flat form when there is no sqlite, and this store answers /match from its rows without exporting at all.

Build state is written only when with_build=True, and then into the build root beside the directory, never inside it. See researcher_profiles.store.db.BuildStateRow.

get(ref: str, eager: bool = False)

Load one profile, backed by a SqlArtifactStorage over its rows.

has_vector_index(ref: str)

Whether ref has chunk vectors. One row, by contract cheap.

The /match dependency scans every profile in the store with it to decide whether ranking is possible at all, so it is a LIMIT 1 and never a fetch.

import_directory(path: str | Path, include_binary: bool = False)

Sugar for put(ResearcherProfile.from_files(path)). Returns the rid.

list_profiles()

Every profile row in the store, ordered by slug.

list_slugs()

Every profile’s display handle, sorted. One column, not one row each.

A projection query: a management host calls this to render a list page, and loading every document blob to read one string off each is how a store gets a reputation for being slow.

manifest_from_rows(ref: str)

(hasPart, subjectOf) from rp_artifacts.

The DB twin of researcher_profiles.manifest.build_manifest. That one walks a directory and this one reads the rows; both answer the same question, what a profile contains.

put(profile: ResearcherProfile, slug: Optional[str] = None, include_binary: bool = False)

Write profile into the store, in one transaction. Returns its rid.

Takes any ResearcherProfile: a directory, a static or remote published one, or one belonging to another store. Upserts on rid and replaces every child row (delete, then insert) rather than diffing: a profile is small, a diff has more ways to be wrong than to be right, and “the rows equal the source” is the only invariant worth having.

Artifacts come from the profile’s recorded manifest (ResearcherProfile.manifest) when it has one, falling back to walking the directory. The recorded manifest is preferred because it is what the published document actually claims; regenerating it here would silently rewrite a published record during an ingest.

include_binary opts into storing binary bodies (a published .bin or an image); without it a binary artifact keeps its manifest row and loses only its bytes. It does not gate vectors: those are shredded into rp_chunk_vectors / rp_profile_vectors on every put, because a queryable vector is not a file body.

put_document(slug: str, document: ProfileDocument)

Create-or-replace a profile’s canonical document only.

If the profile exists, runs an "edit" write unit via save_profile; if new, runs a "create" unit. The write uses the profile’s save_profile so dateModified is stamped correctly and hooks fire.

rename(rid: str, new_slug: str)

Change a profile’s display handle. one update; no child row moves.

This is the whole payoff of keying on rid: a rename is not a data migration. The unique constraint on slug still applies: a store cannot hold two profiles under one handle.

resolve_slug(ref: str)

Map a slug or a rid to the slug.

The mirror of rid_for, which answers with the rid. Both exist because the two are used for different things: rid is the join key every row is written under; slug is what a URL and a human say.

rid_for(ref: str)

The rid of the profile ref names. ref may be a rid or a slug.

Rid wins, mirroring rp where accepting a slug or an ORCID. A bare ORCID needs no separate lookup: an ORCID rid is its ORCID, so it is already the primary key being queried. Raises ProfileNotFoundError naming both lookups that were tried, so “not found” never leaves a caller guessing which namespace was searched.

session()

vector_index(ref: str)

The profile’s chunk-level index, built from its rows.

The rows are serialized into the three published byte shapes and read back by FlatEmbeddingIndex, which is the single read implementation behind all three backends. The alternative, a fourth index class that happens to hold SQL rows, would be a fourth place for cosine to be subtly different.

write_lookup_index()

None: there is no directory to write a lookup file into.

Not a degradation. The file exists so a shell caller can resolve a rid without importing the package; a database has rid_for, which is one indexed query and always current.

Also exported from researcher_profiles.store:

class IngestResult(slug: str, rid: str | None, name: str, level: str, indexed: bool)

Outcome of committing one staged profile directory into a store.

Properties

indexed: bool : Whether a built embedding index is present afterwards. Always False on a store with no filesystem: the index is a .cache/embeddings.sqlite handle, which ArtifactStorage does not cover (see the module docstring).

level: str

name: str

rid: str | None

slug: str

class ProfileNotFoundError

No profile in the store answers to a given rid or slug.

Both a ProfileError and a KeyError. The API layer’s 404 path and every except KeyError around a store lookup read “no such key” (which is exactly what this is), while a management host wants to catch it alongside the package’s other errors. Making it one or the other would force every caller of the other kind to grow a second except clause.

class UploadError

A staged profile directory is malformed, unsafe, or does not load.

Raised by the archive helpers in researcher_profiles.api.upload and by ProfileStore.commit_directory. It lives here, not there, because committing a staged directory is a store operation that both backends perform and neither should have to import the HTTP layer to signal.

build_store(database_url: Optional[str] = None, profiles_dir: Optional[str] = None)

Build the store an operator’s configuration describes.

database_url wins over profiles_dir: naming a database is an explicit act, and a host that has done it does not want the directory that happens to still be on the box. Exactly one composition rule, shared by create_app’s env-driven default and python -m researcher_profiles.api, so the two can never disagree about which store a given environment means.

---

Identity resolution (researcher_profiles.resolve)

The mint-vs-bind policy behind schema.mint_local_rid: given a rid or a free-text name, decide whether it names an existing profile, an undecided one (deferral), or nobody yet (mint). It runs against any ProfileStore, so it works the same whether the caller is the HTTP route (POST /identity/resolve) or a script holding a store directly.

resolve_person(store: Any, rid: Optional[str] = None, name: Optional[str] = None, affiliation: Optional[str] = None, create_new: bool = False)

Resolve a person descriptor to a rid, minting a stub on a true miss.

Resolution is rid-first, cautious on names, and deterministic on mints; see the module docstring for the full pipeline. affiliation is stamped on any minted stub, selects among same-named candidates, and vetoes a match it contradicts. create_new=True skips matching and mints a fresh identity for name, the answer to a deferral whose candidates are all wrong. The resolver picks the id, and calling it twice creates two people.

Raises ResolveError when the request itself is unusable. It never raises for “no such person”; that is the mint path, not an error.

class ResolveResult(rid: Optional[str], created: bool, confidence: str, candidates: tuple[Candidate, ...] = ())

The outcome of one resolve.

rid is None only in the deferred case, distinct from “no match”, which mints. created says whether this call minted the profile. confidence is "exact" for a rid identity, "high" for a corroborated name match or a fresh mint, "low" for a deferral. When a deferral’s candidates are all wrong, re-resolve with create_new=True to mint a fresh identity.

Properties

candidates: tuple[Candidate, …]

confidence: str

created: bool

rid: Optional[str]

class Candidate(rid: str, name: str, affiliation: Optional[str] = None)

One profile an undecidable name could mean.

Properties

affiliation: Optional[str]

name: str

rid: str

class ResolveError

The resolve request is unusable: no identity fields, a malformed rid, an unknown local: rid, a placeholder name, or an ORCID miss with no usable name to mint a stub from.

---

SQL profile store (researcher_profiles.store.db, researcher_profiles.store.sql)

Requires the [sql] extra. See How to store profiles in a database.

This is a peer backing store. A profile in the rp_* tables is a profile: it round-trips back to a byte-identical directory, and SqlArtifactStorage reads and writes it through the same ArtifactStorage contract the filesystem backend implements.

Tables (researcher_profiles.store.db)

class ProfileRow

A whole profile document. Primary key: rid.

document is the record; everything below it is a derived projection rebuilt by from_document on every write. Do not read a projection back into a model, and do not write one from anywhere else.

Properties

affiliation: Optional[str]

affiliation_id: Optional[str]

anchor: Optional[dict] = None

career: list

career_stage_as_of: Optional[str] = None

clinical_training_end_year: Optional[int]

collaborators: list

conforms_to: Optional[str]

content_hash: str = '' : Store-maintained derived state: sha256 over the canonical document and the SOUL text (see content_hash_for). Refreshed inside the write unit, before the pre-commit hooks run.

critiques: list

current_rank: Optional[str] = None

date_modified: Optional[str] = None : The published vintage. Nullable and never defaulted: 45 of the 47 profiles in the reference corpus carry no dateModified at all, and inventing one would be exactly the confident lie researcher_profiles.utils.date_modified exists to prevent.

document: dict : The whole profile.jsonld payload. The source of truth.

email: Optional[str]

expertise_cites_paper_ids: Optional[bool]

field: Optional[str]

first_independent_appointment_year: Optional[int] = None

first_r01_equivalent_year: Optional[int] = None

has_citation_graph: Optional[bool]

has_embedding_index: Optional[bool]

identifier: list

independence: Optional[str]

intellectual_lineage: list

interests: list

job_title: Optional[str]

level: str = 'full'

license: Optional[str] : Reuse terms for the published record (an IRI), when declared.

methodological_commitments: list

name: str

not_interests: list

openalex_id: Optional[str]

orcid: Optional[str] = None : Derived from rid (NULL when the rid is local). A convenience for ORCID joins; join on rid.

paper_stats: Optional[dict] = None

proof: list

provenance: str = '' : Who asserted this profile and on what basis. Required on disk, so it is non-null here too: a consumer must never have to guess whether a row describes a verified self-publication or a third-party assertion.

recurring_positions: list

research_outputs: list

rid: str : The identity: a canonical ORCID or a local: id.

same_as: list

scholar_url: Optional[str]

slug: str : Directory name / display handle. Unique within this store (one store cannot hold two profiles under one handle): a store constraint, never an identity claim. Renameable; see ProfileStore.rename.

subfields: list

summary: Optional[str]

tenure_status: Optional[str]

terminal_degree_type: Optional[str]

terminal_degree_year: Optional[int] = None

training: list

url: Optional[str]

visibility: str = 'public' : Profile-level default privacy tier.

Class Methods

from_document(meta: ProfileDocument, slug: str, document: Optional[dict] = None, soul: str = '')

The one writer of document and every projection derived from it.

meta supplies the identity and the projections; document is the exact serialized payload to store, defaulting to meta’s canonical dump. Pass it explicitly when ingesting a profile whose stored bytes must survive verbatim. A nested node’s un-pruned null is content, and re-dumping the model would rewrite it.

rid comes from meta.rid; there is no override parameter, because a document without a rid cannot load in the first place.

class PaperRow

One work from sources/papers.jsonld.

Keyed by position within the profile, never by paper_id. There is no UNIQUE(profile_rid, paper_id): paper_id is a generated citekey and is not unique within a profile in the real corpus. 13 of 47 reference profiles carry duplicates, and one has 17 genuinely distinct works that collided on the same key. A uniqueness constraint here would refuse to ingest a quarter of the corpus and would silently redefine what a work is. ordinal is the key that actually holds.

record is the whole PaperRecord; the columns beside it are a derived projection for querying. abstract and summary are not projected: they are large and they live in record.

No build field (status, identity_verified, contaminated, …) appears here. Publishing a profile publishes the bibliographic record, not the build’s dirty laundry; build state lives in rp_build_state.

Properties

author_index: Optional[int]

author_position: Optional[str]

cited_by_count: Optional[int]

doi: Optional[str] = None

first_author: Optional[str]

id: Optional[int] = None

is_corresponding: Optional[bool]

is_oa: Optional[bool]

journal: Optional[str]

last_author: Optional[str]

oa_status: Optional[str]

open_access: Optional[bool]

openalex_id: Optional[str]

ordinal: int = 0 : Position in the collection’s hasPart. Re-rendering papers.jsonld from these rows reproduces the original array order.

paper_id: Optional[str] = None

pmcid: Optional[str]

pmid: Optional[str]

profile_rid: str

record: dict : The whole PaperRecord. The source of truth for this work.

source: Optional[str]

title: str

total_authors: Optional[int]

type: Optional[str]

url: Optional[str]

venue: Optional[str]

year: Optional[int] = None

Class Methods

from_record(profile_rid: str, paper: PaperRecord, ordinal: int)

Build a row from a PaperRecord.

class GrantRow

One award from sources/grants.jsonld.

Grants earn a table of their own rather than living only inside the document because cross-profile grant queries (R01-equivalent history for an ESI determination, funder rollups) are the reason grants are in the format at all.

The projection column is grant_id, not id: id is already the autoincrement primary key, and two columns called id meaning different things is how a join goes quietly wrong.

Properties

activity_code: Optional[str] = None

end: Optional[str]

funder: Optional[str] = None

grant_id: str : id: the award’s own id.

id: Optional[int] = None

number: Optional[str]

ordinal: int = 0

profile_rid: str

record: dict : The whole GrantRecord. The source of truth for this award.

role: Optional[str]

source: Optional[str]

start: Optional[str]

status: Optional[str] = None

title: str

url: Optional[str]

Class Methods

from_record(profile_rid: str, grant: GrantRecord, ordinal: int)

Build a row from a GrantRecord.

class ExpertiseTopicRow

One expertise label belonging to a profile.

ordinal preserves the declared order: the labels are a curated, ordered list in profile.jsonld, not a set.

Properties

id: Optional[int] = None

ordinal: int = 0

profile_rid: str

topic: str

class ArtifactRow

One file the profile contains. rp_artifacts is the manifest.

Keyed (profile_rid, content_url), the manifest’s own address space, so personality/SOUL.md, personality/expertise.md, sources/summaries/<paper_id>.summary.md, sources/cv.md, sources/papers/<id>.md, sources/web/<n>-<host>.md, SKILL.md, index.html, sources/citations.json and embeddings/index.json all land in one uniform place: retrievable by role, and privacy-filterable with WHERE visibility = 'public' instead of a second implementation of researcher_profiles.privacy.effective_tiers.

The columns mirror ArtifactRef one for one, with one rename: ArtifactRef.bytes is size_bytes here, because bytes cannot be a column name. The mapping is ArtifactRef.bytes <-> ArtifactRow.size_bytes, both directions, and from_part / to_part are the only places it is applied.

Bodies: text for markdown / JSON / JSON-LD / HTML, data for binary. Binary bodies are opt-in (ProfileStore.put(..., include_binary=True)) because .cache/embeddings.sqlite can be tens of megabytes.

rendered=True marks an artifact whose bytes are regenerated from the relational tables (sources/papers.jsonld, sources/grants.jsonld); both bodies are NULL for those and envelope holds their collection node minus hasPart, so a round-trip is byte-identical.

Properties

content_url: str : The relative path, exactly as ArtifactRef.contentUrl.

data: Optional[bytes] = None

derived_from: list

encoding_format: Optional[str]

envelope: Optional[dict] = None : For a rendered collection: the node minus hasPart (about, dateModified, @context, conformsTo, …).

id: Optional[int] = None

manifest_slot: str = DEFAULT_MANIFEST_SLOT : Which manifest list this entry belongs to: hasPart or subjectOf.

name: Optional[str]

ordinal: int = 0

paper_id: Optional[str] = None

profile_rid: str

rendered: bool = False

role: Optional[str] = None

sha256: Optional[str]

size_bytes: Optional[int] : ArtifactRef.bytes. Renamed; see the class docstring.

text: Optional[str]

type_: Optional[str]

visibility: str = 'public'

Class Methods

from_part(profile_rid: str, part: ArtifactRef, manifest_slot: str = DEFAULT_MANIFEST_SLOT, ordinal: int = 0, text: Optional[str] = None, data: Optional[bytes] = None, rendered: bool = False, envelope: Optional[dict] = None)

Build a row from one manifest entry plus its body.

Methods

apply_part(part: ArtifactRef)

Copy a manifest entry’s fields onto this row, in place.

The write path for a document whose manifest changed (the SQL store’s save_profile, reached from edit.set_visibility and rp profile visibility): the entry’s metadata lands on the row, and the document’s manifest is then regenerated from the rows, so the two cannot disagree.

to_part()

Rebuild the manifest entry this row records.

class ChunkVectorRow

One chunk’s embedding, as a queryable row. rp_chunk_vectors.

The SQL store’s vectors, shredded out of the per-profile .cache/embeddings.sqlite at ingest so they can be selected rather than unpacked. Before this table the whole index file lived in a single rp_artifacts BLOB, which meant a SQL-backed deployment had to export every profile to a temp directory before it could rank anything.

Storage: vector is row-major little-endian float32, the same bytes researcher_profiles.embeddings._sqlite.serialize_vec writes, in a portable LargeBinary column. Deliberately not sqlite-vec (a SQLite-only extension needing raw CREATE VIRTUAL TABLE DDL) and not pgvector (Postgres-only): these tables must load unchanged on SQLite in tests and on Postgres in production, which is the whole point of this module. Cosine runs in numpy on the read side, through FlatEmbeddingIndex, which is brute force over a few hundred rows per profile and is exactly what the filesystem and HTTP backends already do.

Rows are the public subset, the same one write_flat_export publishes: embeddings are partially invertible, so a chunk built from a restricted source never reaches this table any more than it reaches a .bin. text is not stored for the same reason the published form drops it.

The key mirrors the sqlite index’s own UNIQUE(source_type, source_id, chunk_index), scoped to the profile.

Properties

backend_spec: str = ''

char_count: Optional[int]

chunk_index: int

dim: int

id: Optional[int] = None

ordinal: int = 0 : Blob order: source_type, source_id, chunk_index, assigned at insert so a read can restore the published row order without re-sorting.

profile_rid: str

section: Optional[str] : chunks.json mirror; carried so the flat form round-trips exactly.

source_id: str

source_type: str

vector: bytes : Row-major little-endian float32, dim floats. See the class docstring.

class ProfileVectorRow

One profile-level vector. rp_profile_vectors.

kind="centroid" is the one that exists today: the L2-normalized mean of every chunk vector in the profile’s index, computed at ingest by the same function the filesystem backend uses (researcher_profiles.embeddings.profile_vec._centroid_vec) so the two backends report the same number for the same profile.

Separate from ChunkVectorRow because the registry’s hot path wants the whole roster’s centroids in one SELECT of N rows, not N scans of every profile’s chunks. This table is the relational form of the published collection/embeddings/<backend>.bin.

kind is part of the key so summary / expertise vectors can join later without a migration.

Properties

backend_spec: str = ''

dim: int

kind: str = 'centroid'

profile_rid: str

vector: bytes : Little-endian float32, dim floats. Already L2-normalized.

class BuildStateRow

Build bookkeeping. Not part of the published record.

The SQL analogue of .build/<slug>/ being a sibling tree outside the content root. “Publish this store” means copy rp_profiles, rp_papers, rp_grants, rp_expertise_topics and rp_artifacts and not copy this table; DROP TABLE rp_build_state must stay as free as rm -rf .build/, and every profile must still load afterwards.

It is never rendered into the manifest, never reaches a ProfileExportBundle, and SqlProfileStore.export_directory writes it only when passed with_build=True.

The state is stored whole rather than shredded because BuildState keeps a build-local integer schema_version and makes no external promise; giving its fields columns would create one.

Properties

profile_rid: str

schema_version: int : BuildState’s own private counter. Build-local; never published.

state: dict

create_all(engine: Engine)

Create every rp_* table on engine if not present.

Fresh-instance convenience only. On a deployed Postgres, column evolution goes through numbered SQL migration files, not this::

from sqlmodel import create_engine
from researcher_profiles.store.db import create_all

engine = create_engine("postgresql://user@host/db")
create_all(engine)

get_engine(url: Optional[str] = None, echo: bool = False)

Return (building once per URL) the process-wide SQLAlchemy engine.

The URL resolves through researcher_profiles.store.config.resolve_database_url: explicit argument, then $RESEARCHER_PROFILES_DATABASE_URL. SQLite URLs get check_same_thread=False so one dev/in-memory database is shared across a threadpool.

reset_engine

Drop the cached engine (tests reconfigure the database between cases).

get_session

Yield a Session bound to the shared engine.

Generator form, so it plugs straight into FastAPI’s Depends and can be driven manually elsewhere via next(get_session()).

content_hash_for(document: dict, soul: str)

"sha256:<hex>" over a profile’s canonical content.

Spans two artifacts, NUL-separated: the canonical profile document bytes and the SOUL text, byte-for-byte identically to the filesystem backend’s researcher_profiles.profile.storage.ArtifactStorage.content_hash. Backends that disagree here are not interchangeable, so this is the one definition and the SQL backend stores its output in a column rather than recomputing it per read.

SqlArtifactStorage (researcher_profiles.store.sql)

SqlArtifactStorage(engine_or_url) accepts a SQLAlchemy Engine or a URL. It implements the whole ArtifactStorage contract for one profile’s rows, and SqlProfileStore (above) implements the whole ProfileStore protocol.

class SqlArtifactStorage(store: SqlProfileStore, rid: str, slug: str)

One profile’s rp_* rows.

Writes run in a real transaction: session is the SQLAlchemy Session the unit opened, WriteContext.atomic is True, and the whole unit (every save_* call inside it, the derived-state refresh, and every pre-commit hook) commits or rolls back together.

Nothing here ever touches a filesystem: directory is None and the capabilities that need one refuse with a message naming SqlProfileStore.export_directory.

Properties

EXPORT_REMEDY : What every directory-needing capability says on this backend.

directory: None : Always None: rows are not a directory.

key: str

rid_hint: str : The row key, known without reading a document.

session: Optional[Session] : The session of the open write unit, or None. Every writer goes through this; opening a second connection inside a unit would deadlock against rows the unit already holds. Public because SqlProfileStore.create inserts the bare row through the unit’s own session, via WriteContext.session.

slug: str

Methods

artifact_bytes(content_url: str)

artifact_text(content_url: str)

One artifact’s stored text body, or None.

A rendered collection has no stored body; it is regenerated from rp_papers / rp_grants on the way out.

build_manifest()

Generate the manifest from rp_artifacts, not by walking a path.

The rows are the directory listing.

collection_envelope(content_url: str)

A collection node minus hasPart, so a re-render is faithful.

commit(ctx: WriteContext)

content_hash()

The stored content_hash column: derived state, not recomputed.

The write unit refreshes it (refresh_derived) before the pre-commit hooks run, so a hook reading this observes the new content.

delete_summary(paper_id: str)

index(profile: ResearcherProfile)

No directory, so no sqlite index handle: every operation refuses.

load_build_state()

Build state from rp_build_state; an empty state when absent.

Absent is normal: a published store legitimately has none, the same contract a published directory has. A missing table is absent too: DROP TABLE rp_build_state has to stay as free as rm -rf .build/, so a store published without that table must still serve every profile.

load_citations()

load_document()

load_expertise()

load_grants()

load_papers()

load_persisted_document()

The document currently in the store; {} when absent.

Comparison basis for dateModified, not a load path: errors here are swallowed, exactly as on the filesystem.

The stored document carries hasPart/subjectOf regenerated from the artifact rows, so an empty manifest is persisted as [] here while the canonical model dump the incoming write is compared against omits those keys entirely. Left as-is, content_changed would read the extra [] slots as a change on every write (including an identical re-push) and churn dateModified and content_hash, which would make every re-push look like an edit and break If-Match sync. Empty manifest slots are dropped so this basis matches the model dump; a genuinely non-empty slot is untouched, so removing real parts is still seen as the content change it is.

load_soul()

load_summaries()

locate(parts: str = ())

Display-only locator: a db:// reference naming the row.

new_write_context(profile: ResearcherProfile, kind: str)

Open a transaction and hand it to the unit.

atomic=True: everything inside this unit, hooks included, commits or rolls back together. That is the whole reason a hook is told to branch on ctx.atomic rather than on session is None.

refresh_derived(ctx: WriteContext)

Recompute content_hash inside the unit, before the hooks run.

The digest spans the document and the SOUL, so a soul-only write has to refresh it too. That is why this is the write unit’s job and not save_document’s.

rollback(ctx: WriteContext)

A real rollback: nothing this unit wrote survives.

Contrast the filesystem backend, which can only issue a compensating write for the profile document.

save_build_state(state: BuildState)

save_citations(data: Any)

Write the citation graph; None DELETES the artifact.

Same asymmetry the filesystem backend has: load_citations already models “legitimately absent” as None, so None here is a delete rather than a stored JSON null.

save_document(data: Mapping[str, Any])

Persist the document, and keep it consistent with rp_artifacts.

Three things happen here, in order, and the order is the contract:

1. The incoming manifest is applied onto the artifact rows, so an owner edit (set_visibility) reaches the rows rather than living only in a JSON blob the rows disagree with.
2. hasPart / subjectOf are regenerated from the rows. The rows are the manifest; the document’s copy is a projection of them, which is what makes “the document and the rows disagree” unrepresentable.
3. The regenerated document and every scalar projection are written through the single writer, ProfileRow.from_document.

data arrives already stamped, canonicalized and re-validated by ResearcherProfile.save_profile, so nothing that would fail to load reaches the store.

save_expertise(text: str)

save_grants(grants: list[GrantRecord])

save_papers(papers: list[PaperRecord])

save_soul(text: str)

save_summary(paper_id: str, text: str)

CLI

rp db init | push | pull | list | rm. The database URL resolves --database-url → $RESEARCHER_PROFILES_DATABASE_URL, with no built-in default; a missing URL exits 2.