Metadata-Version: 2.4
Name: semanticanalyser-py
Version: 0.1.3
Summary: A Python binding for the Semantic Analyser service maintained by BODC
Author: Ahmad Mahmoud (CNR internship)
Author-email: ahmad.mahmoud@edu.unifi.it
Maintainer: CNR-IIA Sede di Firenze
Maintainer-email: sede.firenze@iia.cnr.it
License: GPL-3.0
Project-URL: Homepage, https://github.com/ESSI-Lab/semanticanalyser-py
Project-URL: Source, https://github.com/ESSI-Lab/semanticanalyser-py
Project-URL: Tracker, https://github.com/ESSI-Lab/semanticanalyser-py/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: json
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# semanticanalyser-py
A lightweight Python client for the BODC Semantic Analyser API. It helps you discover controlled vocabularies, explore categories, match types and properties, and run term analysis to resolve terms to canonical concepts (with codes and URIs) across marine community vocabularies, including BODC NVS.

The project is authored by Ahmad Mahmoud during his internship at CNR-IIA. 

## Key features
- Retrieve semantic categories
- List supported vocabularies
- Discover supported match types and match properties
- Analyse free-text terms and obtain matched concepts, codes, and vocabularies
- Simple, Pythonic API with minimal dependencies

## Installation
``` bash
pip install semanticanalyser-py
```
## Quick start
``` python
# Basic usage example
from analyser import SemanticAnalyzer, Matchtype, MatchProperty

analyser = SemanticAnalyzer()  # uses the public BODC endpoint by default

# Explore categories
categories = analyser.get_categories()
print("Categories:", categories)

# Choose a category (e.g., first one) and list vocabularies
if categories:
    cat_code = categories[0]["termCode"]
    vocabs = analyser.get_vocabularies(cat_code)
    for v in vocabs:
        print(v)

# Discover matching options
match_types = analyser.getMatchTypes()         # e.g., ["exact", "broad", ...]
match_props = analyser.getMatchProperties()    # e.g., ["prefLabel", "altLabel", ...]

# Prepare the query
terms = ["dissolved oxygen", "chlorophyll a"]

# Optionally filter or construct match types/properties
# (example below demonstrates using them as returned)
analysis = analyser.analyzeTerms(
    terms=terms,
    matchTypes=match_types,
    matchProperties=match_props
)

if analysis:
    for m in analysis.get_matches():
        print(
            m.getMatchingTerm(),
            m.getMatchProperty(),
            m.getMatchType(),
            m.getTermCode(),
            m.getVocabulary(),
            m.getConceptURI(),
        )
```
## When to use this library
- You need to map free-text terms to standardised concepts and codes
- You’re enriching marine dataset descriptions with semantic metadata (URIs, codes, vocabularies)

## Configuration
- Endpoint: By default, the client targets the public BODC Semantic Analyser API. You can override the endpoint:
``` python
  from analyser import SemanticAnalyzer
  analyser = SemanticAnalyzer(endpoint="https://semantics.bodc.ac.uk/api")
```
## Requirements
- Python: 3.8 or newer
- Dependencies: requests

## Roadmap ideas
- Robust pagination and retry logic
- Additional helpers for filtering results
- CLI utilities

## Contributing
Issues and pull requests are welcome.

## License
GNU GPL-3.0
