|
1 | | -# OmniPath Client — Instructions for AI Assistants |
2 | | - |
3 | | -You are working on `omnipath-client`, the new Python client for the OmniPath |
4 | | -molecular biology prior-knowledge web API. |
5 | | - |
6 | | -## Architecture plan |
7 | | - |
8 | | -Read `planning/architecture.md` for the full architecture plan: module |
9 | | -structure, data flow, component descriptions, and implementation order. |
10 | | -The initial specifications are in `planning/initial_specs.md`. |
11 | | - |
12 | | -## The web API |
13 | | - |
14 | | -- **Production**: https://dev.omnipathdb.org/ |
15 | | -- **API docs** (rendered): https://dev.omnipathdb.org/api-docs |
16 | | -- **Server repo**: https://github.com/saezlab/omnipath-present |
17 | | -- **Run locally**: |
18 | | - ``` |
19 | | - git clone git@github.com:saezlab/omnipath-present.git |
20 | | - cd omnipath-present/api-service |
21 | | - uv sync |
22 | | - uv run uvicorn api_service.main:app --reload --port 8081 |
23 | | - curl http://localhost:8081/openapi.json |
24 | | - ``` |
25 | | - |
26 | | -The API uses POST endpoints returning Parquet files. A standard |
27 | | -`openapi.json` will be available soon; until then the HTML API docs page |
28 | | -is the reference. |
29 | | - |
30 | | -## Related local repositories |
31 | | - |
32 | | -| Package | Local path | Purpose | |
33 | | -|---------|-----------|---------| |
34 | | -| **saezverse** | `/home/denes/saezverse/` | Architecture repo: coding conventions, package descriptions, ADRs, plans | |
35 | | -| **pkg_infra** (saezlab_core) | `/home/denes/pypath-new/pkg_infra/` | Config, logging, and session infrastructure for all saezlab packages | |
36 | | -| **download-manager** | — | Cache-aware download manager ([GitHub](https://github.com/saezlab/download-manager)) | |
37 | | -| **cache-manager** | — | SQLite-backed file caching ([GitHub](https://github.com/saezlab/cache-manager)) | |
38 | | -| **annnet** | — | Annotated network/graph library, Polars-backed ([GitHub](https://github.com/saezlab/annnet)) | |
39 | | -| **omnipath** (old client) | — | Legacy Python client being replaced ([GitHub](https://github.com/saezlab/omnipath)) | |
40 | | - |
41 | | -## Key dependencies |
42 | | - |
43 | | -- **pkg_infra (`saezlab_core`)** — all config, logging, and session management |
44 | | - must go through this package. Source at |
45 | | - `/home/denes/pypath-new/pkg_infra/saezlab_core/`. Uses OmegaConf YAML |
46 | | - hierarchy for config, Python `dictConfig` for logging, and a singleton |
47 | | - `Session` object. If it lacks features needed by this client, contribute |
48 | | - upstream rather than building parallel solutions. |
49 | | -- **download-manager** — wraps HTTP downloads with cache-manager integration. |
50 | | - Async support is a goal (not yet implemented). |
51 | | -- **narwhals** — dataframe compatibility layer. Default backend is **polars**. |
52 | | -- **annnet** — for converting interaction/association data to graph objects. |
53 | | - |
54 | | -## Coding conventions |
55 | | - |
56 | | -Follow the saezlab Python coding style documented in |
57 | | -`/home/denes/saezverse/human/guidelines/python-coding-style.md`. Key points: |
58 | | - |
59 | | -- Spaces around `=` in keyword arguments and default values |
60 | | -- Blank lines inside functions before/after blocks and between logical segments |
61 | | -- Argument lists on multiple lines: opening paren on first line, each arg on |
62 | | - its own line, trailing comma, closing paren at original indentation |
63 | | -- Single quotes for strings |
64 | | -- Google (Napoleon) docstring style with triple quotes on separate lines |
65 | | -- Resource names as single words without underscores |
66 | | - |
67 | | -## Package description |
68 | | - |
69 | | -The saezverse package description for this client is at |
70 | | -`/home/denes/saezverse/human/packages/omnipath-client.md`. |
| 1 | +# AGENTS.md — omnipath-client Development Guide |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +omnipath-client is the Python client for OmniPath web services: |
| 6 | +1. **OmniPath Database** — protein interactions, annotations, complexes |
| 7 | + (served by omnipath-present at dev.omnipathdb.org) |
| 8 | +2. **OmniPath Utils** — ID translation, taxonomy, orthology, reference lists |
| 9 | + (served by omnipath-utils at utils.omnipathdb.org) |
| 10 | + |
| 11 | +**Key facts:** |
| 12 | +- Python 3.10+, Hatchling build, BSD-3-Clause license |
| 13 | +- PyPI: `pip install omnipath-client` |
| 14 | +- The lightweight way for users to access OmniPath — no database setup needed |
| 15 | + |
| 16 | +## Architecture |
| 17 | + |
| 18 | +``` |
| 19 | +omnipath_client/ |
| 20 | +├── __init__.py # Public API: OmniPath, entities, interactions, etc. |
| 21 | +├── _client.py # OmniPath class + module-level convenience functions |
| 22 | +├── _query.py # QueryBuilder for the database API |
| 23 | +├── _inventory.py # Auto-populated endpoint definitions from OpenAPI |
| 24 | +├── _download.py # Downloader (wraps dlmachine) |
| 25 | +├── _response.py # Response parsing (Parquet, JSON → DataFrame) |
| 26 | +├── _graph.py # DataFrame → annnet.Graph conversion |
| 27 | +├── _endpoints.py # EndpointDef + ParamDef dataclasses |
| 28 | +├── _errors.py # Exception hierarchy |
| 29 | +├── _constants.py # Base URLs, defaults |
| 30 | +├── _types.py # Type aliases |
| 31 | +├── _session.py # pkg_infra session |
| 32 | +├── _metadata.py # Version |
| 33 | +└── utils/ # OmniPath Utils client |
| 34 | + ├── __init__.py # Re-exports all utils functions |
| 35 | + ├── _base.py # HTTP client (GET/POST to utils.omnipathdb.org) |
| 36 | + ├── _mapping.py # ID translation: map_name, translate, translate_column |
| 37 | + ├── _taxonomy.py # Taxonomy: ensure_ncbi_tax_id, resolve_organism |
| 38 | + ├── _orthology.py # Orthology: translate, translate_column |
| 39 | + └── _reflists.py # Reference lists: get_reflist, is_swissprot |
| 40 | +``` |
| 41 | + |
| 42 | +## Utils module |
| 43 | + |
| 44 | +The `utils` module mirrors the omnipath-utils Python API exactly: |
| 45 | + |
| 46 | +```python |
| 47 | +from omnipath_client.utils import ( |
| 48 | + map_name, translate_column, # ID translation |
| 49 | + ensure_ncbi_tax_id, # Taxonomy |
| 50 | + orthology_translate, # Orthology |
| 51 | + is_swissprot, # Reference lists |
| 52 | + identify, all_mappings, # Discovery |
| 53 | +) |
| 54 | +``` |
| 55 | + |
| 56 | +All functions make HTTP calls to utils.omnipathdb.org. DataFrame functions |
| 57 | +use narwhals for pandas/polars/pyarrow support. |
| 58 | + |
| 59 | +Custom URL: `from omnipath_client.utils._base import set_utils_url` |
| 60 | + |
| 61 | +## Database API |
| 62 | + |
| 63 | +```python |
| 64 | +import omnipath_client as op |
| 65 | +df = op.interactions(entity_ids = ['Q9Y6K9']) |
| 66 | +df = op.entities(entity_types = ['protein']) |
| 67 | +``` |
| 68 | + |
| 69 | +The database API auto-populates endpoint definitions from the server's |
| 70 | +API schema (OpenAPI JSON or HTML parsing fallback), validates query |
| 71 | +parameters, and delivers results as Parquet by default. Supports polars, |
| 72 | +pandas, and pyarrow backends, and optional conversion to annnet Graph |
| 73 | +objects. |
| 74 | + |
| 75 | +## Dependencies |
| 76 | +- `pkg-infra` — logging, config |
| 77 | +- `dlmachine` — downloads + caching |
| 78 | +- `narwhals` — DataFrame ops |
| 79 | +- `requests` — HTTP (for utils module) |
| 80 | + |
| 81 | +## Testing |
| 82 | +```bash |
| 83 | +uv sync |
| 84 | +uv run pytest tests/ -v |
| 85 | +``` |
| 86 | + |
| 87 | +55 tests, all use mocks (no live HTTP). |
0 commit comments