Refresh docs for relations API and lookup/related/fresh; bump 0.3.1

Update README, quickstart, index, the database vignette, and the API
reference to reflect the renamed export endpoints (relations /
annotations) and to introduce the new high-level helpers
(lookup, related), the cache-control helpers (cache_clear, fresh),
and the friendly id-type / participant-type aliases.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: deeenes

README.md

@@ -12,16 +12,24 @@ prior-knowledge web API.
 
 ## Features
 
-- Export **entities**, **interactions**, and **associations** (complexes,
-  pathways, reactions) as DataFrames
+- One-call **`lookup()`** and **`related()`** helpers that resolve
+  free-text queries, fetch the matching entities/relations, and pivot
+  identifiers into named columns — no manual primary-key juggling
+- Friendly id-type aliases (`name`, `chebi`, `hmdb`, `uniprot`,
+  `genesymbol`, `kegg`, …) and participant-type aliases
+  (`protein`, `small_molecule`, …) that hide the MI/OM ontology codes
+- Lower-level primitives: export **entities**, **relations**, and
+  **annotations** as DataFrames; resolve free-text identifiers; slice
+  with paging
 - **Ontology** term lookup, search, and hierarchy trees
 - Multi-backend output: [polars](https://pola.rs/) (default),
   [pandas](https://pandas.pydata.org/), or
   [pyarrow](https://arrow.apache.org/docs/python/)
 - Optional graph conversion to [annnet](https://github.com/saezlab/annnet)
   objects
 - Query validation against the API schema
-- Caching via [download-manager](https://github.com/saezlab/download-manager)
+- Caching via [download-manager](https://github.com/saezlab/download-manager),
+  with a `fresh()` context manager for first-touch refresh
 
 ## Installation
 
@@ -37,20 +45,57 @@ pip install omnipath-client polars
 
 ## Quick start
 
+The two high-level helpers, `lookup()` and `related()`, cover most use
+cases in a single call:
+
 ```python
 import omnipath_client as op
 
-# All interactions as a polars DataFrame
-df = op.interactions()
+# Resolve names and pivot identifiers into named columns
+op.lookup(
+    ['caffeine', 'metformin', 'TP53'],
+    id_types=['name', 'chebi', 'hmdb', 'uniprot', 'genesymbol'],
+)
+
+# Compounds reported in strawberry (FooDB), as a wide joined table
+op.related(
+    subject='Strawberry',
+    sources=['foodb'],
+    id_types=['name', 'chebi', 'hmdb'],
+)
+
+# Drug targets for caffeine (positional arg matches either side)
+op.related(
+    'caffeine',
+    sources=['bindingdb'],
+    id_types=['name', 'uniprot', 'genesymbol'],
+)
+
+# Pathway members from WikiPathways and Reactome at once
+op.related(
+    object=['WP253', 'R-HSA-70171'],
+    sources=['wikipathways', 'reactome'],
+    relation_categories=['annotation'],
+    id_types=['name', 'uniprot', 'chebi'],
+    group_by='object_name',
+)
+```
 
-# Directed interactions only
-df = op.interactions(direction='directed')
+The lower-level primitives are still available for paged scans, raw
+parquet, or graph export:
+
+```python
+# All relations as a polars DataFrame
+df = op.relations()
+
+# Resolve free-text identifiers to entity primary keys
+op.resolve(['caffeine', 'TP53'])
 
 # Human entities
 df = op.entities(taxonomy_ids=['9606'])
 
-# Interactions as an annnet graph
-g = op.interactions(as_graph=True)
+# Relations as an annnet graph
+g = op.relations(as_graph=True)
 
 # Ontology term lookup
 result = op.ontology_terms(['GO:0006915', 'MI:0326'])
@@ -59,6 +104,17 @@ result = op.ontology_terms(['GO:0006915', 'MI:0326'])
 df = op.entities(backend='pandas')
 ```
 
+Cache control:
+
+```python
+# Force a one-shot refresh for everything touched in the block
+with op.fresh():
+    df = op.related('caffeine', sources=['bindingdb'])
+
+# Wipe the entire on-disk cache (e.g. after a server redeploy)
+op.cache_clear()
+```
+
 For more examples, see the [quickstart guide](https://saezlab.github.io/omnipath-client/quickstart/).
 
 ## OmniPath Utils

docs/index.md

@@ -53,17 +53,35 @@ orthology_translate(['TP53', 'EGFR'], source=9606, target=10090)
 ```python
 import omnipath_client as op
 
-df = op.interactions(entity_ids=['Q9Y6K9'])
+# One-call helper: caffeine drug targets with UniProt + gene symbols
+op.related(
+    'caffeine',
+    sources=['bindingdb'],
+    id_types=['name', 'uniprot', 'genesymbol'],
+)
+
+# Or the lower-level primitive
+df = op.relations(entity_pks=['2119890'])
+```
+
+### Resolve and enrich identifiers
+
+```python
+op.lookup(
+    ['caffeine', 'metformin', 'TP53'],
+    id_types=['name', 'chebi', 'hmdb', 'uniprot', 'genesymbol'],
+)
 ```
 
 ### Explore the API
 
 ```python
 import omnipath_client as op
 
-op.endpoints()                                      # all endpoints
-op.params('exports/interactions')                    # available filters
-op.values('exports/interactions', 'entity_types')    # allowed values
+op.endpoints()                                       # all endpoints
+op.params('exports/relations/parquet')                # available filters
+op.values('exports/entities/parquet', 'entity_types') # allowed values
+op.resources()                                        # source catalog
 ```
 
 ## Learn more