tablassist 0.1.0__tar.gz

tablassist-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

tablassist-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: tablassist
+Version: 0.1.0
+Summary: AI-assisted table configuration generation for Tablassert — entity resolution, YAML validation, and Biolink documentation lookup.
+Project-URL: Homepage, https://github.com/SkyeAv/Tablassist
+Project-URL: Source, https://github.com/SkyeAv/Tablassist
+Author-email: Skye Lane Goetz <sgoetz@isbscience.org>
+License-Expression: Apache-2.0
+Keywords: bioinformatics,biolink,data quality control,entity resolution,knowledge graph,ncats translator,tablassert,tablassist,table mining,yaml configuration
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.13
+Requires-Dist: cyclopts>=4.10.1
+Requires-Dist: fastexcel>=0.19.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: polars>=1.39.3
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: tablassert>=7.2.1
+Requires-Dist: textract>=1.6.5
+Requires-Dist: trafilatura>=2.0.0
+Provides-Extra: rt
+Requires-Dist: polars[rtcompat]>=1.39.0; extra == 'rt'
+Requires-Dist: tablassert[rtcompat]>=7.2.1; extra == 'rt'
+Provides-Extra: rtcompat
+Requires-Dist: polars[rtcompat]>=1.39.0; extra == 'rtcompat'
+Requires-Dist: tablassert[rtcompat]>=7.2.1; extra == 'rtcompat'
+Description-Content-Type: text/markdown
+
+# Tablassist CLI
+
+[![PyPI](https://img.shields.io/pypi/v/tablassist.svg)](https://pypi.org/project/tablassist/)
+[![Python](https://img.shields.io/pypi/pyversions/tablassist.svg)](https://pypi.org/project/tablassist/)
+[![License](https://img.shields.io/pypi/l/tablassist.svg)](https://github.com/SkyeAv/Tablassist/blob/master/LICENSE)
+
+Python CLI tool for AI-assisted [Tablassert](https://github.com/SkyeAv/Tablassert) table configuration generation — entity resolution, YAML validation, and Biolink documentation lookup.
+
+## Installation
+
+```bash
+pip install tablassist
+```
+
+An optional extra is available for CPU compatibility:
+
+```bash
+pip install "tablassist[rtcompat]"  # Polars build for CPUs without required instructions
+```
+
+### Requirements
+
+- Python >= 3.13
+- Environment variables `TABLASSIST_USERNAME` and `TABLASSIST_API_KEY` for API-accessing commands
+
+## Usage
+
+```bash
+# Fetch table configuration documentation
+tablassist docs-table-config
+
+# Fetch advanced configuration examples
+tablassist docs-advanced-examples
+
+# Fetch the CLI tutorial
+tablassist docs-tutorial
+```
+
+### Entity Resolution
+
+```bash
+# Search for entity CURIEs by term
+tablassist search-curies "breast cancer"
+
+# Get canonical info for a specific CURIE
+tablassist get-curie-info "MONDO:0007254"
+
+# Search gene CURIEs within an NCBI taxon
+tablassist search-gene-curies "BRCA1" --ncbi-taxon 9606
+
+# Resolve an NCBI Taxon ID from an organism name
+tablassist resolve-taxon-id "Homo sapiens"
+```
+
+### Biolink Reference
+
+```bash
+# List all supported categories, predicates, or qualifiers
+tablassist list-categories
+tablassist list-predicates
+tablassist list-qualifiers
+
+# Fetch documentation for a specific Biolink element
+tablassist docs-category "Gene"
+tablassist docs-predicate "interacts_with"
+tablassist docs-qualifier "qualified_predicate"
+```
+
+### YAML Validation
+
+```bash
+# Validate a full config file
+tablassist validate-config-file config.yaml
+
+# Validate a single section from a YAML string
+tablassist validate-section-str '<yaml>'
+
+# Validate a full config from a YAML string
+tablassist validate-config-str '<yaml>'
+
+# Get the Section JSON schema
+tablassist section-schema
+```
+
+### Data Preview
+
+```bash
+# List sheets in an Excel file
+tablassist excel-sheets data.xlsx
+
+# Preview rows from an Excel sheet
+tablassist preview-excel data.xlsx "Sheet1" 10
+
+# Preview rows from a CSV file
+tablassist preview-csv data.csv 10
+
+# Extract text from a document (PDF, DOCX, etc.)
+tablassist extract-text document.pdf
+```
+
+### PMC Archive Download
+
+```bash
+# Download and extract a PMC tar archive
+tablassist download-pmc-tar 12345 --dest-dir ./output
+```
+
+## Development
+
+```bash
+uv sync                              # install dependencies
+uv run ruff check .                  # lint
+uv run ruff check --fix .            # lint with auto-fix
+uv run ruff format .                 # format
+uv run pyright                       # type check
+uv run pytest                        # run all tests
+```
+
+## License
+
+[Apache License 2.0](../LICENSE)

tablassist-0.1.0/README.md

@@ -0,0 +1,121 @@
+# Tablassist CLI
+
+[![PyPI](https://img.shields.io/pypi/v/tablassist.svg)](https://pypi.org/project/tablassist/)
+[![Python](https://img.shields.io/pypi/pyversions/tablassist.svg)](https://pypi.org/project/tablassist/)
+[![License](https://img.shields.io/pypi/l/tablassist.svg)](https://github.com/SkyeAv/Tablassist/blob/master/LICENSE)
+
+Python CLI tool for AI-assisted [Tablassert](https://github.com/SkyeAv/Tablassert) table configuration generation — entity resolution, YAML validation, and Biolink documentation lookup.
+
+## Installation
+
+```bash
+pip install tablassist
+```
+
+An optional extra is available for CPU compatibility:
+
+```bash
+pip install "tablassist[rtcompat]"  # Polars build for CPUs without required instructions
+```
+
+### Requirements
+
+- Python >= 3.13
+- Environment variables `TABLASSIST_USERNAME` and `TABLASSIST_API_KEY` for API-accessing commands
+
+## Usage
+
+```bash
+# Fetch table configuration documentation
+tablassist docs-table-config
+
+# Fetch advanced configuration examples
+tablassist docs-advanced-examples
+
+# Fetch the CLI tutorial
+tablassist docs-tutorial
+```
+
+### Entity Resolution
+
+```bash
+# Search for entity CURIEs by term
+tablassist search-curies "breast cancer"
+
+# Get canonical info for a specific CURIE
+tablassist get-curie-info "MONDO:0007254"
+
+# Search gene CURIEs within an NCBI taxon
+tablassist search-gene-curies "BRCA1" --ncbi-taxon 9606
+
+# Resolve an NCBI Taxon ID from an organism name
+tablassist resolve-taxon-id "Homo sapiens"
+```
+
+### Biolink Reference
+
+```bash
+# List all supported categories, predicates, or qualifiers
+tablassist list-categories
+tablassist list-predicates
+tablassist list-qualifiers
+
+# Fetch documentation for a specific Biolink element
+tablassist docs-category "Gene"
+tablassist docs-predicate "interacts_with"
+tablassist docs-qualifier "qualified_predicate"
+```
+
+### YAML Validation
+
+```bash
+# Validate a full config file
+tablassist validate-config-file config.yaml
+
+# Validate a single section from a YAML string
+tablassist validate-section-str '<yaml>'
+
+# Validate a full config from a YAML string
+tablassist validate-config-str '<yaml>'
+
+# Get the Section JSON schema
+tablassist section-schema
+```
+
+### Data Preview
+
+```bash
+# List sheets in an Excel file
+tablassist excel-sheets data.xlsx
+
+# Preview rows from an Excel sheet
+tablassist preview-excel data.xlsx "Sheet1" 10
+
+# Preview rows from a CSV file
+tablassist preview-csv data.csv 10
+
+# Extract text from a document (PDF, DOCX, etc.)
+tablassist extract-text document.pdf
+```
+
+### PMC Archive Download
+
+```bash
+# Download and extract a PMC tar archive
+tablassist download-pmc-tar 12345 --dest-dir ./output
+```
+
+## Development
+
+```bash
+uv sync                              # install dependencies
+uv run ruff check .                  # lint
+uv run ruff check --fix .            # lint with auto-fix
+uv run ruff format .                 # format
+uv run pyright                       # type check
+uv run pytest                        # run all tests
+```
+
+## License
+
+[Apache License 2.0](../LICENSE)

tablassist-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "tablassist"
+version = "0.1.0"
+description = "AI-assisted table configuration generation for Tablassert — entity resolution, YAML validation, and Biolink documentation lookup."
+authors = [
+    { name = "Skye Lane Goetz", email = "sgoetz@isbscience.org" },
+]
+keywords = [
+    "knowledge graph",
+    "bioinformatics",
+    "entity resolution",
+    "ncats translator",
+    "yaml configuration",
+    "table mining",
+    "tablassert",
+    "tablassist",
+    "biolink",
+    "data quality control",
+]
+readme = "README.md"
+license = "Apache-2.0"
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: Pydantic",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "cyclopts>=4.10.1",
+    "fastexcel>=0.19.0",
+    "httpx>=0.28.1",
+    "polars>=1.39.3",
+    "pydantic>=2.12.5",
+    "pyyaml>=6.0.3",
+    "tablassert>=7.2.1",
+    "textract>=1.6.5",
+    "trafilatura>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SkyeAv/Tablassist"
+Source = "https://github.com/SkyeAv/Tablassist"
+
+[build-system]
+requires = [
+    "hatchling",
+]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = [
+    "./src/tablassist",
+]
+
+[project.scripts]
+tablassist = "tablassist.cli:serve"
+
+[project.optional-dependencies]
+rtcompat = [
+    "tablassert[rtcompat]>=7.2.1",
+    "polars[rtcompat]>=1.39.0",
+]
+rt = [
+    "tablassist[rtcompat]",
+]
+
+[tool.uv]
+override-dependencies = [
+    "six>=1.16.0",
+]
+
+[dependency-groups]
+dev = [
+    "mkdocs>=1.6.1",
+    "pyright>=1.1.408",
+    "pytest>=9.0.2",
+    "ruff>=0.15.6",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["test"]
+
+[tool.ruff]
+line-length = 120
+indent-width = 4
+target-version = "py313"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = true

tablassist-0.1.0/src/tablassist/cli.py

@@ -0,0 +1,268 @@
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Any, Literal, Optional, Union
+
+import fastexcel
+import httpx
+import polars as pl
+import textract
+import yaml
+from cyclopts import App
+from tablassert.enums import Categories, Predicates, Qualifiers
+from tablassert.ingests import from_yaml
+from tablassert.models import Section
+
+from tablassist.utils import (
+    get_biolink_html_documentation,
+    get_json_response,
+    get_static_content,
+    parse_yaml_string,
+    validate_section,
+)
+
+CLI: App = App()
+
+
+@CLI.command
+def docs_table_config() -> str:
+    """Fetch Tablassert table configuration spec documentation."""
+    url: str = "https://raw.githubusercontent.com/SkyeAv/Tablassert/main/docs/configuration/table.md"
+    return get_static_content(url)
+
+
+@CLI.command
+def docs_advanced_examples() -> str:
+    """Fetch advanced table configuration examples documentation."""
+    url: str = "https://raw.githubusercontent.com/SkyeAv/Tablassert/main/docs/configuration/advanced-example.md"
+    return get_static_content(url)
+
+
+@CLI.command
+def docs_tutorial() -> str:
+    """Fetch Tablassert CLI tutorial documentation."""
+    url: str = "https://raw.githubusercontent.com/SkyeAv/Tablassert/blob/main/docs/tutorial.md"
+    return get_static_content(url)
+
+
+@CLI.command
+def example_no_sections() -> str:
+    """Fetch a production YAML config example without sections."""
+    url: str = (
+        "https://raw.githubusercontent.com/glusman-team/MOKGConfiguration/refs/heads/master/TABLE/MBKG/ALAM1.yaml"
+    )
+    return get_static_content(url)
+
+
+@CLI.command
+def example_with_sections() -> str:
+    """Fetch a production YAML config example with sections."""
+    url: str = (
+        "https://raw.githubusercontent.com/glusman-team/MOKGConfiguration/refs/heads/master/TABLE/MBKG/BLANTON1.yaml"
+    )
+    return get_static_content(url)
+
+
+TABLASSIST_USERNAME: str = os.environ.get("TABLASSIST_USERNAME", "")
+TABLASSIST_API_KEY: str = os.environ.get("TABLASSIST_API_KEY", "")
+
+
+@CLI.command
+def search_curies(term: str) -> Union[list[Any], dict[str, Any]]:
+    """Search CURIE candidates by term via Configurator API."""
+    url: str = "https://hypatia.systemsbiology.net/configurator-api/search-for-curies"
+    params: dict[str, Any] = {"username": TABLASSIST_USERNAME, "api-key": TABLASSIST_API_KEY, "term": term}
+
+    return get_json_response(url, params)
+
+
+@CLI.command
+def get_curie_info(curie: str) -> Union[list[Any], dict[str, Any]]:
+    """Resolve a single canonical CURIE record."""
+    url: str = "https://hypatia.systemsbiology.net/configurator-api/get-canonical-curie-info"
+    params: dict[str, Any] = {"username": TABLASSIST_USERNAME, "api-key": TABLASSIST_API_KEY, "curie": curie}
+
+    return get_json_response(url, params)
+
+
+@CLI.command
+def download_pmc_tar(pmc_id: int, dest_dir: Path = Path(".")) -> dict[str, Any]:
+    """Download and extract a PMC tar archive by PMC ID."""
+    url: str = "https://hypatia.systemsbiology.net/configurator-api/download-from-pmc-tars"
+
+    params: dict[str, Any] = {"username": TABLASSIST_USERNAME, "api-key": TABLASSIST_API_KEY, "pmc-id": pmc_id}
+
+    with httpx.stream("GET", url, params=params) as r:
+        if r.status_code == 404:
+            error: dict[str, Any] = r.json()
+            return error
+
+        d: str = r.headers["content-disposition"]
+        matches: object = re.search(r"filename=(.+)", d)
+
+        filename: str = matches.group(1) if matches else "download.tar.xz"
+        p: Path = dest_dir / filename
+        with p.open("wb") as f:
+            for chunk in r.iter_bytes():
+                f.write(chunk)
+
+    cmd: list[str] = ["tar", "-xvf", f"{p}", "&&", "ls", "-lh", f"{dest_dir}"]
+    r: Any = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+
+    return {"status": "ok", "stdout": r.stdout, "stderr": r.stderr}
+
+
+@CLI.command
+def search_gene_curies(term: str, ncbi_taxon: int = 9606) -> Union[list[Any], dict[str, Any]]:
+    """Search gene CURIE candidates by term within an NCBI taxon."""
+    url: str = "https://hypatia.systemsbiology.net/configurator-api/search-for-gene-curies-in-ncbi-taxon"
+    params: dict[str, Any] = {
+        "username": TABLASSIST_USERNAME,
+        "api-key": TABLASSIST_API_KEY,
+        "term": term,
+        "ncbi-taxon-id": ncbi_taxon,
+    }
+
+    return get_json_response(url, params)
+
+
+@CLI.command
+def resolve_taxon_id(organism_name: str) -> Union[list[Any], dict[str, Any]]:
+    """Resolve an NCBI Taxon ID from an organism name."""
+    url: str = "https://hypatia.systemsbiology.net/configurator-api/get-ncbi-taxon-id-from-organism-name"
+    params: dict[str, Any] = {
+        "username": TABLASSIST_USERNAME,
+        "api-key": TABLASSIST_API_KEY,
+        "organism-name": organism_name,
+    }
+
+    return get_json_response(url, params)
+
+
+@CLI.command
+def list_categories() -> list[str]:
+    """List all supported Biolink categories."""
+    return [x.value for x in Categories]
+
+
+@CLI.command
+def list_predicates() -> list[str]:
+    """List all supported Biolink predicates."""
+    return [x.value for x in Predicates]
+
+
+@CLI.command
+def list_qualifiers() -> list[str]:
+    """List all supported Biolink qualifiers."""
+    return [x.value for x in Qualifiers]
+
+
+@CLI.command
+def section_schema() -> dict[str, Any]:
+    """Return the Section Pydantic model as JSON schema."""
+    return Section.model_json_schema()
+
+
+@CLI.command
+def validate_section_str(yaml_string: str) -> dict[str, Any]:
+    """Validate a single YAML table configuration section from a string."""
+    raw: Any = parse_yaml_string(yaml_string)
+    if isinstance(raw, dict) and "error" in raw:
+        return raw
+
+    return validate_section(raw)
+
+
+@CLI.command
+def validate_config_str(yaml_string: str) -> Union[dict[str, Any], list[dict[str, Any]]]:
+    """Validate a full YAML table configuration from a string."""
+    raw: Any = parse_yaml_string(yaml_string)
+    if isinstance(raw, dict) and "error" in raw:
+        return raw
+
+    sections: list[dict[str, Any]] = raw if isinstance(raw, list) else [raw]
+
+    errors: list[dict[str, Any]] = []
+    for s in sections:
+        errors += [validate_section(s)]
+
+    return errors
+
+
+@CLI.command
+def validate_config_file(yaml_file: Path) -> Union[dict[str, Any], list[dict[str, Any]]]:
+    """Validate a full YAML table configuration from a file path."""
+    try:
+        raw: Any = from_yaml(yaml_file)
+    except yaml.scanner.ScannerError as e:  # pyright: ignore
+        return {"error": f"YAML Syntax error at line {e.problem_mark.line + 1}: {e.problem}"}
+    except yaml.parser.ParserError as e:  # pyright: ignore
+        return {"error": f"YAML Parser error: {e}"}
+    except yaml.YAMLError as e:
+        return {"error": f"YAML error: {e}"}
+
+    sections: list[dict[str, Any]] = raw if isinstance(raw, list) else [raw]
+
+    errors: list[dict[str, Any]] = []
+    for s in sections:
+        errors += [validate_section(s)]
+
+    return errors
+
+
+@CLI.command
+def docs_category(category: str) -> str:
+    """Fetch Biolink documentation for a specific category."""
+    return get_biolink_html_documentation(category) or f"ERROR | {category} is not a supported biolink category"
+
+
+@CLI.command
+def docs_predicate(predicate: str) -> str:
+    """Fetch Biolink documentation for a specific predicate."""
+    return get_biolink_html_documentation(predicate) or f"ERROR | {predicate} is not a supported biolink predicate"
+
+
+@CLI.command
+def docs_qualifier(qualifier: str) -> str:
+    """Fetch Biolink documentation for a specific qualifier."""
+    return get_biolink_html_documentation(qualifier) or f"ERROR | {qualifier} is not a supported biolink qualifier"
+
+
+@CLI.command
+def extract_text(file: Path, extension: Optional[str] = None) -> str:
+    """Extract text from a file using textract (PDF, DOCX, etc.)."""
+    if file.suffix == "pdf":
+        return textract.process(file, method="pdfminer")
+    elif extension:
+        return textract.process(file, extension=extension)
+    else:
+        return textract.process(file)
+
+
+@CLI.command
+def excel_sheets(file: Path) -> list[str]:
+    """List sheet names in an Excel spreadsheet."""
+    wb: Any = fastexcel.read_excel(file)
+    return wb.sheet_names
+
+
+@CLI.command
+def preview_excel(
+    file: Path, sheet_name: str, n_rows: int, engine: Literal["calamine", "openpyxl", "xlsx2csv"] = "calamine"
+) -> dict[str, Any]:
+    """Preview the first N rows of an Excel sheet as a dict."""
+    df: pl.DataFrame = pl.read_excel(source=file, sheet_name=sheet_name, engine=engine, infer_schema_length=None)
+    df = df.head(n_rows)
+    return df.to_dict(as_series=False)
+
+
+@CLI.command
+def preview_csv(file: Path, n_rows: int, separator: str = ",") -> dict[str, Any]:
+    """Preview the first N rows of a CSV/tabular file as a dict."""
+    df: pl.DataFrame = pl.read_csv(source=file, n_rows=n_rows, separator=separator)
+    return df.to_dict(as_series=False)
+
+
+def serve() -> None:
+    CLI()