Metadata-Version: 2.1
Name: geneea-nlp-client
Version: 1.6.0
Summary: The SDK library and command-line interface to Geneea Interpretor, an NLP REST API.
Home-page: https://geneea.com
Author: Geneea Analytics s.r.o
Author-email: support@geneea.com
License: UNKNOWN
Project-URL: Documentation, https://help.geneea.com/sdk/index.html
Project-URL: Source Code, https://bitbucket.org/geneea/sdk
Keywords: geneea python interpretor nlp nlu api cli
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
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: License :: OSI Approved :: Apache Software License
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests~=2.25
Provides-Extra: examples
Requires-Dist: pandas>=0.22; extra == "examples"

# Geneea NLP Client SDK

A Python SDK for the **Geneea Interpretor** - a Natural Language Processing REST API that extracts linguistic insights from text documents.

## Features

The SDK provides access to Geneea's NLP capabilities including language detection, named entity recognition (persons, organizations, locations), semantic tagging, sentiment analysis, and relationship extraction between entities.

## Installation

```bash
pip install geneea-nlp-client
```

Supports Python 3.8 - 3.13.

## Quick Start

```python
from geneeanlpclient import g3

# Create a request builder with desired analyses
builder = g3.Request.Builder(
    analyses=[g3.AnalysisType.ENTITIES, g3.AnalysisType.SENTIMENT]
)

# Analyze text using the API client
with g3.Client.create(userKey="YOUR_API_KEY") as client:
    analysis = client.analyze(builder.build(
        id="doc1",
        text="Angela Merkel visited Paris last Tuesday."
    ))
    
    # Access results
    for entity in analysis.entities:
        print(f"{entity.type}: {entity.stdForm}")
    
    if analysis.docSentiment:
        print(f"Sentiment: {analysis.docSentiment.label}")
```

You can also set the API key via the `GENEEA_API_KEY` environment variable.

## Analysis Types

| Type        | Description                          |
|-------------|--------------------------------------|
| `ENTITIES`  | Named entity recognition             |
| `TAGS`      | Semantic tagging and topic extraction|
| `RELATIONS` | Entity relationships and attributes  |
| `SENTIMENT` | Sentiment analysis                   |
| `LANGUAGE`  | Language detection                   |
| `ALL`       | All analyses                         |

## Advanced Usage

**Structured document input:**
```python
builder = g3.Request.Builder(analyses=[g3.AnalysisType.ALL])
request = builder.build(
    id="article1",
    paraSpecs=[
        g3.ParaSpec.title("Author Elena Marsh Releases New Historical Novel"),
        g3.ParaSpec.lead("The acclaimed writer returns with a story set in 19th century Prague."),
        g3.ParaSpec.body("First paragraph of the article."),
        g3.ParaSpec.body("Second paragraph of the article.")
    ]
)
```

Note: The Interpretor (General API) can accept any number of paragraphs, but always returns at most one of each type: title, lead, and body.
For title and lead this is usually not a limitation (there is typically only one of each), but if there are multiple body paragraphs in the input, they are concatenated into a single body paragraph with "\n\n" as separator in the output.

**Domain-specific analysis:**
```python
builder = g3.Request.Builder(
    analyses=[g3.AnalysisType.ENTITIES, g3.AnalysisType.TAGS],
    domain=g3.Domain.NEWS,  # News media articles
    language=g3.LanguageCode.EN
)
```

**With item-level sentiment and mentions:**
```python
builder = g3.Request.Builder(
    analyses=[g3.AnalysisType.ENTITIES, g3.AnalysisType.SENTIMENT],
    returnMentions=True,
    returnItemSentiment=True
)
```

**Working with results:**
```python
# Iterate through document structure
for paragraph in analysis.paragraphs:
    print(f"Paragraph type: {paragraph.type}")
    for sentence in paragraph.sentences:
        print(f"  Sentence: {sentence.text}")
        print(f"  First word: {sentence.tokens[0].text}")

# Entity mentions with positions
for entity in analysis.entities:
    for mention in entity.mentions:
        print(f"{entity.stdForm} found at: {mention.tokens.charSpan}")
```

## Dependencies

- `requests~=2.25` - HTTP communication
- `pandas>=0.22` (optional) - For example scripts with Excel export

## Development

The SDK is built using Bitbucket Pipelines.
The pipelines are run at least once a month to keep the SonarQube token valid.

## Documentation

- [API Documentation](https://help.geneea.com/api_general/index.html#api-general)
- [SDK Documentation](https://help.geneea.com/sdk/index.html)
- [Source Code](https://bitbucket.org/geneea/sdk)

## License

Apache License 2.0


