Metadata-Version: 2.4
Name: FindOrg
Version: 1.0.1
Summary: Extract organization names from text using LLMs (OpenAI or Google Gemini).
Author: Luiz Felipe Neves
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/FindOrg/
Keywords: ner,named-entity-recognition,organizations,openai,gemini,llm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0
Requires-Dist: pandas>=1.5
Provides-Extra: excel
Requires-Dist: openpyxl>=3.0; extra == "excel"
Dynamic: license-file

# FindOrg — Named Entity Recognition for Organizations using LLMs

FindOrg is a Python package that performs Named Entity Recognition (NER) targeting **organizations** within a given text. It leverages large language models from **OpenAI** or **Google Gemini** to extract organization names and return them as a tidy pandas DataFrame.

## Installation

```bash
pip install FindOrg
```

To enable saving results as Excel files (`.xlsx`), install with the optional extra:

```bash
pip install FindOrg[excel]
```

## Quick start

```python
from findorg import org

text = (
    "In the heart of Silicon Valley, a collaboration has emerged between "
    "global tech giants such as Google, Apple, and Meta, aiming to "
    "revolutionize the digital landscape."
)

# OpenAI (default provider)
df = org(text, api_key="YOUR_OPENAI_API_KEY")
print(df)
```

```
  Organizations
0        Google
1         Apple
2          Meta
```

### Using Google Gemini instead

```python
df = org(text, provider="gemini", api_key="YOUR_GEMINI_API_KEY")
```

### API keys via environment variables (recommended)

If `api_key` is omitted, FindOrg reads it from the environment: `OPENAI_API_KEY` for OpenAI or `GEMINI_API_KEY` for Gemini. This keeps keys out of your source code:

```python
df = org(text)                      # uses OPENAI_API_KEY
df = org(text, provider="gemini")   # uses GEMINI_API_KEY
```

### Analyzing multiple texts at once

Pass a list of strings. The result gains a `Text_ID` column (1-based index of the input text):

```python
texts = [
    "Petrobras signed an agreement with the World Bank.",
    "The event took place in Brasília, with no companies involved.",
]

df = org(texts, verbose=True)
print(df)
```

```
   Text_ID Organizations
0        1     Petrobras
1        1    World Bank
```

### Saving results

```python
df = org(text, save_path="organizations.xlsx")   # Excel (requires openpyxl)
df = org(text, save_path="organizations.csv")    # CSV
```

## Arguments

| Argument    | Type                 | Default        | Description |
|-------------|----------------------|----------------|-------------|
| `text`      | `str` or `list[str]` | *required*     | Text(s) to be analyzed. |
| `api_key`   | `str`                | `None`         | API key for the chosen provider. If omitted, read from `OPENAI_API_KEY` or `GEMINI_API_KEY`. |
| `provider`  | `str`                | `"openai"`     | `"openai"` or `"gemini"`. |
| `model`     | `str`                | provider default | Model name. Defaults to `gpt-4o-mini` (OpenAI) or `gemini-3.5-flash` (Gemini). |
| `save_path` | `str`                | `None`         | If given, saves the result to this path (`.xlsx` or `.csv`). |
| `unique`    | `bool`               | `False`        | If `True`, removes duplicated organization names. |
| `verbose`   | `bool`               | `False`        | If `True`, prints progress messages. |

## Returns

`pandas.DataFrame` with one row per extracted organization:

- Single text input → column `Organizations`.
- List input → columns `Text_ID` and `Organizations`.

## Extraction rules

- Geographic locations (countries, states, cities) are not extracted — organization names only.
- When an organization's name is followed by its acronym in brackets, only the full name is extracted.
- Texts with no organizations return an empty DataFrame.

## Migrating from version 0.x

Version 1.0.0 introduces breaking changes:

| Version 0.x                      | Version 1.0.0 |
|----------------------------------|---------------|
| `from FindOrg import org`        | `from findorg import org` (lowercase) |
| `org(text, openai_key="...")`    | `org(text, api_key="...")` |
| `save=True` (fixed filename)     | `save_path="organizations.xlsx"` (any path, `.xlsx` or `.csv`) |
| OpenAI only, `gpt-3.5-turbo`     | OpenAI or Gemini; default model is now `gpt-4o-mini` |

The change of default model was required because OpenAI is shutting down `gpt-3.5-turbo` in October 2026.

## How to cite

Neves, L. F. F. (2026). FindOrg: Named Entity Recognition for Organizations using LLMs (Version 1.0.0) [Python package]. https://pypi.org/project/FindOrg/

## Contact

luiz.felipe@ufg.br
