Metadata-Version: 2.4
Name: ra-bio
Version: 0.2.0
Summary: Public runtime library for Japanese microorganism risk and law reference data
Project-URL: Repository, https://github.com/Ameyanagi/ra-bio
Author-email: Ameyanagi <contact@ameyanagi.com>
License: MIT
License-File: LICENSE
Keywords: bio,law-screening,microorganism,risk-assessment,taxonomy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# ra-bio

Public runtime library for microorganism risk-reference data derived from NITE/MRINDA.

`ra_bio` is the canonical non-MCP API for direct consumers.
It ships a bundled SQLite database generated by the `ra-bio-scraper` repository.

## What it does

- resolves microorganism names against canonical names and synonyms
- supports fuzzy search for misspellings and historical names
- returns aggregated organism profiles with structured law/risk annotations
- keeps raw evidence under `risk_annotations` while also exposing grouped sections like `regulations` and `biosafety`

## Install

```bash
pip install ra-bio
```

```bash
uv add ra-bio
```

## Usage

```python
from ra_bio import get_bio_database, search_organisms, lookup_bio_profile

db = get_bio_database()

lookup = db.lookup(query="Mortierella wolfii", language="ja")
search = db.search(query="Granulicatella adiacen", limit=5, min_score=0.6)
sources = db.get_source_snapshots()

search_via_helper = search_organisms(query="Granulicatella adiacen", limit=5, min_score=0.6)
lookup_via_helper = lookup_bio_profile(query="Mortierella wolfii", language="ja")
```

## Examples

Search a synonym or misspelling and get the current accepted name:

```python
from ra_bio import get_bio_database

db = get_bio_database()
result = db.search(query="Mortierella wolfii", limit=3, min_score=0.6)

print(result["hits"][0]["canonical_name"])
# Actinomortierella wolfii
```

Look up a canonical profile with host and disease information:

```python
from ra_bio import get_bio_database

db = get_bio_database()
profile = db.lookup(query="Vibrio salmonicida", language="ja")

print(profile["profile"]["canonical_name"])
# Aliivibrio salmonicida

print(profile["profile"]["hosts"])
# ['サケ科魚類']

print(profile["profile"]["diseases"])
# ['冷水性ビブリオ病*']
```

Look up law and biosafety annotations in a stable structure:

```python
from ra_bio import get_bio_database

db = get_bio_database()
profile = db.lookup(query="Anaplasma bovis", language="ja")

print(profile["profile"]["regulations"]["cartagena"]["values"])
# ['クラス2']

print(profile["profile"]["biosafety"]["bsl_bsj"]["values"])
# ['BSL2']
```

Inspect the bundled source-update metadata:

```python
from ra_bio import get_bio_database

db = get_bio_database()
for row in db.get_source_snapshots():
    print(row["dataset_id"], row["source_filename"], row["source_version"], row["fetched_at"])
```

Example search result:

```json
{
  "cluster_id": "ORG-000093",
  "canonical_name": "Actinomortierella wolfii",
  "preferred_scientific_name": "Actinomortierella wolfii",
  "datasets": ["fungi"],
  "score": 1.0,
  "match_type": "exact_raw",
  "matched_value": "Mortierella wolfii",
  "match_sources": ["canonical_name", "scientific_name", "synonym:m"],
  "regulation_keys": [],
  "biosafety_keys": ["trba"]
}
```

Example lookup summary:

```json
{
  "matched": true,
  "profile": {
    "canonical_name": "Granulicatella adiacens",
    "scientific_names": [
      "Abiotrophia adiacens",
      "Granulicatella adiacens",
      "Streptococcus adjacens"
    ],
    "datasets": ["bacteria"],
    "regulations": {
      "cartagena": {
        "values": ["クラス2"]
      }
    },
    "biosafety": {
      "bsl_bsj": {
        "values": ["BSL1*"]
      },
      "trba": {
        "values": ["2"]
      }
    }
  }
}
```

Example source snapshot metadata:

```json
[
  {
    "dataset_id": "bacteria",
    "source_filename": "risk_bacteria_20260120.csv",
    "source_version": "20260120"
  },
  {
    "dataset_id": "bacteria_fish",
    "source_filename": "risk_bacteria_fish_20240924.csv",
    "source_version": "20240924"
  },
  {
    "dataset_id": "fungi",
    "source_filename": "risk_fungi.xlsx",
    "source_version": "20260120"
  }
]
```

Public runtime API:

- `get_bio_database(db_path: str | None = None)`
- `search_organisms(query, mode="auto", dataset=None, limit=20, min_score=0.6, db_path=None)`
- `lookup_bio_profile(query=None, scientific_name=None, language="ja", db_path=None)`
- `get_bio_source_snapshots(db_path=None)`
- `get_bio_runtime_status(db_path=None)`
- `BioDatabase.get_source_snapshots()`
- `BioDatabase.get_runtime_status()`
- `BioDatabase.lookup(query=None, scientific_name=None, language="ja")`
- `BioDatabase.search(query, mode="auto", dataset=None, limit=20, min_score=0.6)`

Lookup payload highlights:

- `profile["regulations"]`: 法令・制度の注記を安定キーで参照
- `profile["biosafety"]`: BSL / TRBA などの注記を参照
- `profile["designations"]`: 魚病菌・植物病原菌・住環境菌などの指定区分を参照
- `profile["pathogen_profiles"]`: 魚病データセット由来の宿主・疾病プロファイルを参照
- `profile["risk_annotations"]`: 元データに近い証跡を保持

Default behavior:

- if `db_path` is omitted, `ra_bio` uses the packaged bundled SQLite database
- `db_path` may point to:
  - a direct SQLite file
  - a checked-out `ra-bio` directory containing `bio.sqlite3`

## Runtime artifact

The canonical runtime artifact is the bundled SQLite database:

- packaged path: `src/ra_bio/data/bio.sqlite3`
- published repo artifact: `bio.sqlite3`

Normal installed consumers should rely on the packaged bundled database.
The public repo intentionally stays small: detailed raw CSV/HTML retention is handled by `ra-bio-scraper`, not by `ra-bio`.

## Data sources

The current dataset is derived from these NITE/MRINDA downloads:

- `https://www.nite.go.jp/mrinda/list/risk/download/bacteria`
- `https://www.nite.go.jp/mrinda/list/risk/download/bacteria_fish`
- `https://www.nite.go.jp/mrinda/list/risk/download/fungi`

## Source update metadata

Source update information is part of the public runtime data.

- the SQLite bundle stores `source_filename`, `source_version`, `fetched_at`, and `content_hash`
- the public repo keeps `parsed/source_snapshots.jsonl`
- consumers can inspect the same information via `BioDatabase.get_source_snapshots()`

Detailed raw CSV files, extracted CSVs, and HTML snapshots are retained in `ra-bio-scraper`.

## Development

```bash
uv sync --group dev
uv run pre-commit install
uv run pre-commit run --all-files
uv run pytest -q
```

## Release

PyPI publishing is handled by GitHub Actions only when a matching `v*` tag is
pushed. See [docs/release.md](docs/release.md) for the cleanup and release
checklist.
