### Start tm2tb Web App with Docker Compose

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Command to start the tm2tb web application using Docker Compose, ensuring it's built.

```bash
docker compose up --build web
```

--------------------------------

### Get tm2tb CLI Help using Docker Compose

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Command to retrieve the command-line interface help information for tm2tb by running it in a Docker Compose container.

```bash
docker compose run --rm tm2tb tm2tb --help
```

--------------------------------

### tm2tb CLI for Glossary Generation

Source: https://context7.com/luismond/tm2tb/llms.txt

Shows how to install and run the tm2tb command-line tool for extracting biterms and generating glossaries from bilingual files. Supports various input formats and aligner choices.

```bash
# Install and run locally
pip install -e .
tm2tb --src en --tgt es \
      --in tests/data/test_bitext_en_es.csv \
      --out output/glossary.csv
```

```bash
# Run via Docker Compose
docker compose run --rm tm2tb tm2tb \
  --src en --tgt es \
  --in data/sample.tmx \
  --out out/glossary.csv
```

```bash
# Available --aligner choices: heuristic (default), t5, hybrid
tm2tb --src en --tgt de \
      --in data/en_de.xlsx \
      --out output/en_de_glossary.csv \
      --aligner heuristic
```

```bash
# Run the test suite
docker compose run --rm test
```

```bash
# Get help
docker compose run --rm tm2tb tm2tb --help
```

--------------------------------

### TransformerModel and spaCy Model Configuration

Source: https://context7.com/luismond/tm2tb/llms.txt

Demonstrates loading multilingual sentence-transformer models and spaCy models for specific languages. Shows how to get embedding dimensions, encode text, and access token properties.

```python
from tm2tb.core.config import get_spacy_model, trf_model, TransformerModel

# Access the default LaBSE transformer (loaded at import)
embedding_dims = trf_model.get_sentence_embedding_dimension()
print(embedding_dims)  # 768

vectors = trf_model.encode(["giant panda", "panda gigante"])
print(vectors.shape)   # (2, 768)

# Get a spaCy model for a specific language
nlp_en = get_spacy_model('en')
doc = nlp_en("The giant panda lives in China.")
for token in doc:
    print(token.text, token.pos_)

# Load an alternative transformer model (trades size for speed)
# Options: 'LaBSE', 'setu4993/smaller-LaBSE',
#          'distiluse-base-multilingual-cased-v1',
#          'distiluse-base-multilingual-cased-v2',
#          'paraphrase-multilingual-MiniLM-L12-v2',
#          'paraphrase-multilingual-mpnet-base-v2'
small_model = TransformerModel("paraphrase-multilingual-MiniLM-L12-v2").load()
vectors_small = small_model.encode(["giant panda", "panda gigante"])

# Supported language codes for get_spacy_model
for lang in ['en', 'es', 'de', 'fr', 'pt', 'it']:
    model = get_spacy_model(lang)
    print(f"{lang}: {model.lang}")

# Unsupported language raises ValueError
try:
    get_spacy_model('zh')
except ValueError as e:
    print(e)  # "zh model has not been installed!"
```

--------------------------------

### Build and Run tm2tb with Docker

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Commands to build the Docker image for tm2tb and run it, exposing port 5000. Alternatively, use 'docker compose up --build' for live development.

```bash
docker build -t tm2tb .
docker run -p 5000:5000 tm2tb
```

```bash
docker compose up --build
```

--------------------------------

### BitermExtractor Usage

Source: https://context7.com/luismond/tm2tb/llms.txt

Demonstrates how to initialize and use the BitermExtractor with different inputs and parameters.

```APIDOC
## BitermExtractor

### Description
Extracts bilingual terms (biterms) from sentence pairs or a full bitext.

### Initialization with a single bilingual sentence pair (tuple input)
```python
from tm2tb import BitermExtractor

# Assuming 'en' and 'es' are defined language variables
extractor = BitermExtractor((en, es))
biterms = extractor.extract_terms()
print(biterms[['src_term', 'tgt_term', 'similarity', 'frequency', 'biterm_rank']])
```

### Lower similarity threshold
```python
biterms_loose = BitermExtractor((en, es)).extract_terms(similarity_min=0.5)
print(biterms_loose[:5])
```

### Restrict to multi-word terms (2–3 tokens)
```python
biterms_mw = BitermExtractor((en, es)).extract_terms(span_range=(2, 3))
print(biterms_mw[:5])
```

### Filter by POS tags on both sides
```python
biterms_pos = BitermExtractor((en, es)).extract_terms(incl_pos=['ADJ', 'NOUN'])
print(biterms_pos[:4])
```

### Explicit language codes
```python
biterms_explicit = BitermExtractor(
    (en, es), src_lang='en', tgt_lang='es'
).extract_terms()
```

### Initialization with a full bitext (list of tuples input)
```python
bitext = [
    ("The giant panda lives in mountain ranges.", "El panda gigante vive en cordilleras."),
    ("Bamboo makes up 99% of its diet.",          "El bambú representa el 99% de su dieta."),
    ("Giant pandas are endangered species.",       "Los pandas gigantes son especies en peligro."),
]

extractor_bt = BitermExtractor(bitext, src_lang='en', tgt_lang='es')
biterms_bt = extractor_bt.extract_terms()
print(biterms_bt[['src_term', 'tgt_term', 'similarity', 'frequency', 'biterm_rank']].head(5))
```

### Return as list of BiTerm namedtuples
```python
raw_biterms = extractor_bt.extract_terms(return_as_table=False)
for bt in raw_biterms[:3]:
    print(bt.src_term, '->', bt.tgt_term, f'(sim={bt.similarity}, freq={bt.frequency})')
```
```

--------------------------------

### Run tm2tb Unit Tests using Docker Compose

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Command to execute the unit tests for tm2tb within a Docker Compose environment.

```bash
docker compose run --rm test
```

--------------------------------

### BitextReader Usage

Source: https://context7.com/luismond/tm2tb/llms.txt

Demonstrates how to use BitextReader to load parallel bilingual files in various formats.

```APIDOC
## BitextReader — Read parallel bilingual files into a bitext list

### Description
Loads a bilingual file in supported formats (.csv, .xlsx, .tmx, .mqxliff, .mxliff) and returns a list of (src, tgt) string tuples. It includes validation for file size, extension, and content.

### Reading from CSV
```python
from tm2tb import BitextReader

bitext = BitextReader('tests/data/test_bitext_en_es.csv').read_bitext()
print(bitext[0])
# ('The giant panda also known as the panda bear...', 'El panda gigante...')
```

### Reading from Excel (.xlsx)
```python
bitext_xlsx = BitextReader('tests/data/test_bitext_en_es.xlsx').read_bitext()
```

### Reading from TMX
```python
bitext_tmx = BitextReader('tests/data/test_bitext_en_es.tmx').read_bitext()
```

### Reading from memoQ XLIFF (.mqxliff)
```python
bitext_mq = BitextReader('tests/data/test_bitext_en_es.mqxliff').read_bitext()
```

### Reading from Phrase/Memsource XLIFF (.mxliff)
```python
bitext_mx = BitextReader('tests/data/test_bitext_en_es.mxliff').read_bitext()
```

### Full pipeline example
```python
from tm2tb import BitextReader, BitermExtractor

bitext = BitextReader('tests/data/test_bitext_en_es.csv').read_bitext()
extractor = BitermExtractor(bitext, src_lang='en', tgt_lang='es')
biterms = extractor.extract_terms()
print(biterms[['src_term', 'tgt_term', 'similarity', 'frequency', 'biterm_rank']].head(10))
# Output:
#                    src_term                  tgt_term  similarity  frequency  biterm_rank
# 0               giant panda             panda gigante      0.9758          8       1.0000
# 1                     panda                     panda      1.0000          8       0.5966
# 2                 red panda                panda rojo      0.9807          1       0.1203
# 3                   Ursidae                   Ursidae      1.0000          2       0.0829
# 4             prepared food      alimentos preparados      0.9623          1       0.0735
```

### Error handling
```python
try:
    bitext = BitextReader('path/to/large_file.csv', max_size=2000000).read_bitext()
except ValueError as e:
    print(f"File error: {e}")
    # e.g. "Oversized file. Max size: 2.0 MB." or "Unsupported file extension."
```

### Saving extracted biterms
```python
biterms.to_csv('output/glossary.csv', index=False)
```
```

--------------------------------

### REST API POST /

Source: https://context7.com/luismond/tm2tb/llms.txt

Details the Flask API endpoint for performing biterm extraction via a POST request.

```APIDOC
## REST API — POST `/` (Flask endpoint)

### Description
The Flask API exposes a single `POST /` endpoint that accepts a JSON payload with source/target sentence texts and language codes, runs `BitermExtractor`, and returns the extracted biterms as a JSON string. Runs on port 5000 by default.

### Request
```python
import json
import requests

# Assuming the Flask server is running on http://localhost:5000
url = "http://localhost:5000/"

payload = {
    "sentences": [
        ("The giant panda lives in mountain ranges.", "El panda gigante vive en cordilleras.")
    ],
    "src_lang": "en",
    "tgt_lang": "es"
}

headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, data=json.dumps(payload), headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}, {response.text}")
```

### Response Example (Success)
```json
{
  "biterms": [
    {
      "src_term": "giant panda",
      "tgt_term": "panda gigante",
      "similarity": 0.9758,
      "frequency": 1,
      "biterm_rank": 1.0
    }
  ]
}
```
```

--------------------------------

### Extract Biterms from a Full Bitext (List of Tuples)

Source: https://context7.com/luismond/tm2tb/llms.txt

Initialize BitermExtractor with a list of (source, target) sentence tuples. The extracted biterms can be returned as a DataFrame or a list of namedtuples.

```python
bitext = [
    ("The giant panda lives in mountain ranges.", "El panda gigante vive en cordilleras."),
    ("Bamboo makes up 99% of its diet.",          "El bambú representa el 99% de su dieta."),
    ("Giant pandas are endangered species.",       "Los pandas gigantes son especies en peligro."),
]

extractor_bt = BitermExtractor(bitext, src_lang='en', tgt_lang='es')
biterms_bt = extractor_bt.extract_terms()
print(biterms_bt[['src_term', 'tgt_term', 'similarity', 'frequency', 'biterm_rank']].head(5))
```

```python
raw_biterms = extractor_bt.extract_terms(return_as_table=False)
for bt in raw_biterms[:3]:
    print(bt.src_term, '->', bt.tgt_term, f'(sim={bt.similarity}, freq={bt.frequency})')
```

--------------------------------

### Extract Biterms from CSV using Docker Compose

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Command to run tm2tb via Docker Compose to extract biterms from a CSV file, specifying input, output, and source/target languages.

```bash
docker compose run --rm tm2tb tm2tb --in data/sample.csv --out out/glossary.csv --src en --tgt es
```

--------------------------------

### Read Parallel Bilingual Files with BitextReader

Source: https://context7.com/luismond/tm2tb/llms.txt

Use BitextReader to load parallel files from various formats (.csv, .xlsx, .tmx, .mqxliff, .mxliff) into a list of (source, target) tuples. Supports file size and extension validation.

```python
bitext = BitextReader('tests/data/test_bitext_en_es.csv').read_bitext()
print(bitext[0])
```

```python
bitext_xlsx = BitextReader('tests/data/test_bitext_en_es.xlsx').read_bitext()
```

```python
bitext_tmx = BitextReader('tests/data/test_bitext_en_es.tmx').read_bitext()
```

```python
bitext_mq = BitextReader('tests/data/test_bitext_en_es.mqxliff').read_bitext()
```

```python
bitext_mx = BitextReader('tests/data/test_bitext_en_es.mxliff').read_bitext()
```

```python
bitext = BitextReader('tests/data/test_bitext_en_es.csv').read_bitext()
extractor = BitermExtractor(bitext, src_lang='en', tgt_lang='es')
biterms = extractor.extract_terms()
print(biterms[['src_term', 'tgt_term', 'similarity', 'frequency', 'biterm_rank']].head(10))
```

```python
try:
    bitext = BitextReader('path/to/large_file.csv', max_size=2000000).read_bitext()
except ValueError as e:
    print(f"File error: {e}")
```

```python
biterms.to_csv('output/glossary.csv', index=False)
```

--------------------------------

### Extract Biterms from a Single Bilingual Sentence Pair

Source: https://context7.com/luismond/tm2tb/llms.txt

Initialize BitermExtractor with a tuple of source and target sentences. The extracted biterms can be filtered by similarity, span range, and POS tags.

```python
extractor = BitermExtractor((en, es))
biterms = extractor.extract_terms()
print(biterms[['src_term', 'tgt_term', 'similarity', 'frequency', 'biterm_rank']])
```

```python
biterms_loose = BitermExtractor((en, es)).extract_terms(similarity_min=0.5)
print(biterms_loose[:5])
```

```python
biterms_mw = BitermExtractor((en, es)).extract_terms(span_range=(2, 3))
print(biterms_mw[:5])
```

```python
biterms_pos = BitermExtractor((en, es)).extract_terms(incl_pos=['ADJ', 'NOUN'])
print(biterms_pos[:4])
```

```python
biterms_explicit = BitermExtractor(
    (en, es), src_lang='en', tgt_lang='es'
).extract_terms()
```

--------------------------------

### Language Detection with tm2tb.core.utils.detect_lang

Source: https://context7.com/luismond/tm2tb/llms.txt

Utilizes the `detect_lang` function to identify the ISO language code of single strings or lists of strings. Handles unsupported languages by raising a ValueError.

```python
from tm2tb.core.utils import detect_lang

# Single sentence
lang = detect_lang("The giant panda is native to China.")
print(lang)  # 'en'

lang = detect_lang("El panda gigante es originario de China.")
print(lang)  # 'es'

# List of sentences (samples up to 50 for efficiency)
sentences = [
    "Der Große Panda ist in China heimisch.",
    "Er ernährt sich hauptsächlich von Bambus.",
    "Große Pandas gelten als bedrohte Tierart.",
]
lang = detect_lang(sentences)
print(lang)  # 'de'

# Error handling — unsupported or undetectable language
try:
    lang = detect_lang("これはテストです。")  # Japanese — not supported by default
except ValueError as e:
    print(e)
    # 'Identified language as "ja", but it is not supported.
    #  Please install the corresponding spaCy model.'
```

--------------------------------

### Python API Request to tm2tb Service

Source: https://context7.com/luismond/tm2tb/llms.txt

Demonstrates how to send a POST request to the tm2tb API with JSON payload for text similarity analysis. Includes basic error handling for API responses.

```python
import requests
import json

payload = {
    "src_text": (
        "The giant panda is a bear native to South Central China."
        " It is characterised by its bold black-and-white coat."
    ),
    "tgt_text": (
        "El panda gigante es un oso originario del centro-sur de China."
        " Se caracteriza por su llamativo pelaje blanco y negro."
    ),
    "src_lang": "en",
    "tgt_lang": "es",
    "similarity_min": 0.9
}

response = requests.post(
    "http://localhost:5000/",
    json=json.dumps(payload),
    headers={"Content-Type": "application/json"}
)

if response.ok:
    biterms = json.loads(response.text)
    print(biterms)
    # Returns JSON with columns: src_term, src_tags, src_rank,
    #                             tgt_term, tgt_tags, tgt_rank,
    #                             similarity, frequency, biterm_rank
else:
    print("API error:", response.text)
```

```bash
# Equivalent curl request
curl -X POST http://localhost:5000/ \
  -H "Content-Type: application/json" \
  -d '"{\"src_text\": \"The giant panda is a bear native to China.\", \"tgt_text\": \"El panda gigante es un oso de China.\", \"src_lang\": \"en\", \"tgt_lang\": \"es\", \"similarity_min\": 0.9}"'
```

--------------------------------

### Open Interactive Bash Shell in tm2tb Container

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Command to access an interactive Bash shell inside the running tm2tb container for debugging or manual operations.

```bash
docker compose exec tm2tb bash
```

--------------------------------

### BitermExtractor

Source: https://context7.com/luismond/tm2tb/llms.txt

Extracts bilingual term pairs (biterms) from a sentence pair or a full bitext. It identifies monolingual terms, builds a cross-lingual similarity matrix using embeddings, matches similar pairs, and returns ranked biterms with similarity scores and frequency. A minimum similarity threshold controls match quality.

```APIDOC
## BitermExtractor

### Description
Extracts bilingual term pairs from a sentence pair or bitext. It accepts either a single tuple (one source/target sentence pair) or a list of tuples (a full bitext). It extracts monolingual terms from each side, builds a cross-lingual cosine similarity matrix using shared multilingual embeddings, matches the most similar pairs, and returns ranked bilingual term pairs (biterms) with similarity scores, frequency, and individual POS tags. A `similarity_min` threshold (default 0.9) controls match quality.

### Usage
```python
from tm2tb import BitermExtractor

en = (
    "The giant panda, also known as the panda bear (or simply the panda)"
    " is a bear native to South Central China."
)
es = (
    "El panda gigante, también conocido como oso panda (o simplemente panda),"
    " es un oso originario del centro-sur de China."
)

# Example with a single sentence pair
biterm_extractor = BitermExtractor(sentence_pair=(en, es))
biterms = biterm_extractor.extract_biterms()
print(biterms[:5])

# Example with a full bitext (list of sentence pairs)
bitext = [(en, es), (en, es)] # Replace with actual bitext data
biterm_extractor_bitext = BitermExtractor(bitext)
biterms_bitext = biterm_extractor_bitext.extract_biterms()
print(biterms_bitext[:5])
```

### Parameters
- **data** (tuple or list) - Either a tuple of two strings representing a source and target sentence, or a list of such tuples representing a full bitext.
- **similarity_min** (float, optional) - The minimum cosine similarity score for a pair of terms to be considered a match. Defaults to 0.9.
- **model_name** (str, optional) - The name of the sentence-transformer model to use for embeddings. Defaults to 'sentence-transformers/LaBSE'.

### Returns
- list - A list of dictionaries, where each dictionary represents a bilingual term pair (biterm) with keys such as 'source_term', 'target_term', 'source_pos', 'target_pos', 'similarity', and 'frequency'.
```

--------------------------------

### Extract Bilingual Term Pairs with BitermExtractor

Source: https://context7.com/luismond/tm2tb/llms.txt

Use BitermExtractor to find aligned term pairs (biterms) between source and target sentences. It uses cross-lingual embeddings and cosine similarity. A minimum similarity threshold can be set.

```python
from tm2tb import BitermExtractor

en = (
    "The giant panda, also known as the panda bear (or simply the panda)"
    " is a bear native to South Central China."
)
es = (
    "El panda gigante, también conocido como oso panda (o simplemente panda),"
    " es un oso originario del centro-sur de China."
)
```

--------------------------------

### Extract Terms from Spanish Sentence

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Instantiate TermExtractor with a Spanish sentence to automatically detect the language and extract terms. The output format is similar to English term extraction.

```python
es_sentence = (
    "El panda gigante, también conocido como oso panda (o simplemente panda),"
    " es un oso originario del centro-sur de China. Se caracteriza por su"
    " llamativo pelaje blanco y negro, y su cuerpo rotundo. El nombre 'panda"
    " gigante' se usa en ocasiones para distinguirlo del panda rojo, un"
    " mustélido parecido. Aunque pertenece al orden de los carnívoros, el panda"
    " gigante es folívoro, y más del 99 % de su dieta consiste en brotes y"
    " hojas de bambú. En la naturaleza, los pandas gigantes comen ocasionalmente"
    " otras hierbas, tubérculos silvestres o incluso carne de aves, roedores o"
    " carroña. En cautividad, pueden alimentarse de miel, huevos, pescado, hojas"
    " de arbustos, naranjas o plátanos."
    )
```

```python
extractor = TermExtractor(es_sentence)  # Instantiate extractor with sentence
terms = extractor.extract_terms()       # Extract terms
print(terms[:10])
```

```text
term        pos_tags    rank  frequency
0          panda gigante    [PROPN, ADJ]  1.0000          3
1             panda rojo  [PROPN, PROPN]  0.9023          1
2                  panda         [PROPN]  0.9013          6
3              oso panda  [PROPN, PROPN]  0.7563          1
4                gigante           [ADJ]  0.4877          3
5               roedores          [NOUN]  0.4641          1
6               plátanos          [NOUN]  0.4434          1
7          pelaje blanco     [NOUN, ADJ]  0.3851          1
8  tubérculos silvestres     [NOUN, ADJ]  0.3722          1
9                  bambú         [PROPN]  0.3704          1
```

--------------------------------

### Extract Terms from English Sentence

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Instantiate TermExtractor with an English sentence and extract terms. The output includes the term, its part-of-speech tags, rank, and frequency.

```python
from tm2tb import TermExtractor

en_sentence = (
    "The giant panda, also known as the panda bear (or simply the panda)"
    " is a bear native to South Central China. It is characterised by its"
    " bold black-and-white coat and rotund body. The name 'giant panda'"
    " is sometimes used to distinguish it from the red panda, a neighboring"
    " musteloid. Though it belongs to the order Carnivora, the giant panda"
    " is a folivore, with bamboo shoots and leaves making up more than 99%"
    " of its diet. Giant pandas in the wild will occasionally eat other grasses,"
    " wild tubers, or even meat in the form of birds, rodents, or carrion."
    " In captivity, they may receive honey, eggs, fish, shrub leaves,"
    " oranges, or bananas."
    )
```

```python
extractor = TermExtractor(en_sentence)  # Instantiate extractor with sentence
terms = extractor.extract_terms()       # Extract terms
print(terms[:10])
```

```text
term        pos_tags    rank  frequency
0          panda          [NOUN]  1.0000          6
1    giant panda     [ADJ, NOUN]  0.9462          3
2     panda bear    [NOUN, NOUN]  0.9172          1
3      red panda     [ADJ, NOUN]  0.9152          1
4      Carnivora         [PROPN]  0.6157          1
5  Central China  [PROPN, PROPN]  0.5306          1
6        bananas          [NOUN]  0.4813          1
7        rodents          [NOUN]  0.4218          1
8        Central         [PROPN]  0.3930          1
9    bear native     [NOUN, ADJ]  0.3695          1
```

--------------------------------

### Extract Bilingual Terms with Part-of-Speech Tags (Python)

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Use this snippet for bilingual term extraction, filtering by specified part-of-speech tags. Requires the BitermExtractor class and a tuple of sentences.

```python
>>> extractor = BitermExtractor((en_sentence, es_sentence))
>>> biterms = extractor.extract_terms(incl_pos=['ADJ', 'NOUN'])
>>> print(biterms[:10])
```

--------------------------------

### Extract Matched Terms from Sentence Pairs

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Use BitermExtractor to find and match terms between a source and target sentence. The output includes source and target terms, their similarity score, frequency, and a biterm rank.

```python
from tm2tb import BitermExtractor

extractor = BitermExtractor((en_sentence, es_sentence)) # Instantiate extractor with sentences
biterms = extractor.extract_terms()                     # Extract biterms
print(biterms[:7])
```

```text
src_term        tgt_term  similarity  frequency  biterm_rank
0  giant panda   panda gigante      0.9758          1       1.0000
1    red panda      panda rojo      0.9807          1       0.9385
2        panda           panda      1.0000          1       0.7008
3      oranges        naranjas      0.9387          1       0.3106
4       bamboo           bambú      0.9237          1       0.2911
5        China           China      1.0000          1       0.2550
6  rotund body  cuerpo rotundo      0.9479          1       0.2229
```

--------------------------------

### Extract Terms from Monolingual Text with TermExtractor

Source: https://context7.com/luismond/tm2tb/llms.txt

Use TermExtractor for monolingual term extraction. Language is auto-detected by default. Options include restricting term length, filtering by POS tags, and setting minimum frequency.

```python
from tm2tb import TermExtractor

sentence = (
    "The giant panda, also known as the panda bear (or simply the panda)"
    " is a bear native to South Central China. It is characterised by its"
    " bold black-and-white coat and rotund body. The name 'giant panda'"
    " is sometimes used to distinguish it from the red panda, a neighboring"
    " musteloid. Though it belongs to the order Carnivora, the giant panda"
    " is a folivore, with bamboo shoots and leaves making up more than 99%"
    " of its diet."
)

# Basic extraction — returns a pandas DataFrame sorted by rank
extractor = TermExtractor(sentence)          # language auto-detected as 'en'
terms = extractor.extract_terms()
print(terms[:5])
# Output:
#          term        pos_tags    rank  frequency
# 0       panda          [NOUN]  1.0000          6
# 1 giant panda     [ADJ, NOUN]  0.9462          3
# 2  panda bear    [NOUN, NOUN]  0.9172          1
# 3   red panda     [ADJ, NOUN]  0.9152          1
# 4   Carnivora         [PROPN]  0.6157          1

# Restrict term length to 2–3 words
terms_2_3 = extractor.extract_terms(span_range=(2, 3))
print(terms_2_3[:3])
# Output:
#               term               pos_tags    rank  frequency
# 0      giant panda            [ADJ, NOUN]  1.0000          3
# 1       panda bear           [NOUN, NOUN]  0.9693          1
# 2        red panda            [ADJ, NOUN]  0.9672          1

# Filter by POS tags — only ADJ and NOUN spans
terms_adj_noun = extractor.extract_terms(incl_pos=['ADJ', 'NOUN'])
print(terms_adj_noun[:5])
# Output:
#           term      pos_tags    rank  frequency
# 0        panda        [NOUN]  1.0000          6
# 1  giant panda   [ADJ, NOUN]  0.9462          3
# 2   panda bear  [NOUN, NOUN]  0.9172          1
# 3    red panda   [ADJ, NOUN]  0.9152          1
# 4      bananas        [NOUN]  0.4813          1

# Require minimum frequency of 2
terms_freq2 = extractor.extract_terms(freq_min=2)
print(terms_freq2[:3])

# Explicit language code — skips auto-detection
extractor_es = TermExtractor(sentence, lang='es')
terms_es = extractor_es.extract_terms()

# Return raw spaCy spans instead of a DataFrame
spans = extractor.extract_terms(return_as_table=False)
for span in spans[:3]:
    print(span._.true_case, span._.rank, span._.frequency)
```

--------------------------------

### Extract Bilingual Terms with Span Range (Python)

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Use this snippet for bilingual term extraction, specifying a span range for the terms. Requires the BitermExtractor class and a tuple of sentences.

```python
>>> extractor = BitermExtractor((en_sentence, es_sentence))
>>> biterms = extractor.extract_terms(span_range=(2,3))
>>> print(biterms[:10])
```

--------------------------------

### Extract Terms from Bilingual Document

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Reads a bilingual document and extracts aligned terms. Requires the BitextReader and BitermExtractor classes.

```python
>>> from tm2tb import BitextReader
>>> path = 'tests/panda_bear_english_spanish.csv'
>>> bitext = BitextReader(path).read_bitext()   # Read bitext
>>> extractor = BitermExtractor(bitext)         # Instantiate extractor with bitext
>>> biterms = extractor.extract_terms()         # Extract terms
>>> print(biterms[:10])
```

--------------------------------

### TermExtractor

Source: https://context7.com/luismond/tm2tb/llms.txt

Extracts terms from a monolingual text. It identifies candidate noun/adjective spans, encodes them, computes similarity to the document embedding, and returns ranked terms with POS tags, similarity rank, and frequency. Language is auto-detected if not provided.

```APIDOC
## TermExtractor

### Description
Extracts terms from a monolingual sentence or text. It uses spaCy for Part-of-Speech tagging to identify candidate noun/adjective spans, encodes them with a sentence-transformer, computes cosine similarity to the source document embedding, and returns ranked terms with POS tags, similarity-based rank, and frequency. Language is auto-detected if not provided.

### Usage
```python
from tm2tb import TermExtractor

sentence = (
    "The giant panda, also known as the panda bear (or simply the panda)"
    " is a bear native to South Central China. It is characterised by its"
    " bold black-and-white coat and rotund body. The name 'giant panda'"
    " is sometimes used to distinguish it from the red panda, a neighboring"
    " musteloid. Though it belongs to the order Carnivora, the giant panda"
    " is a folivore, with bamboo shoots and leaves making up more than 99%"
    " of its diet."
)

# Basic extraction
extractor = TermExtractor(sentence)
terms = extractor.extract_terms()
print(terms[:5])

# Restrict term length to 2–3 words
terms_2_3 = extractor.extract_terms(span_range=(2, 3))
print(terms_2_3[:3])

# Filter by POS tags
terms_adj_noun = extractor.extract_terms(incl_pos=['ADJ', 'NOUN'])
print(terms_adj_noun[:5])

# Require minimum frequency of 2
terms_freq2 = extractor.extract_terms(freq_min=2)
print(terms_freq2[:3])

# Explicit language code
extractor_es = TermExtractor(sentence, lang='es')
terms_es = extractor_es.extract_terms()

# Return raw spaCy spans
spans = extractor.extract_terms(return_as_table=False)
for span in spans[:3]:
    print(span._.true_case, span._.rank, span._.frequency)
```

### Parameters
- **text** (str) - The input text or sentence(s) to process.
- **lang** (str, optional) - The language code for the text. If not provided, language is auto-detected. Defaults to None.
- **span_range** (tuple, optional) - A tuple specifying the minimum and maximum length of term spans (e.g., (1, 2) for single words or two-word phrases). Defaults to (1, 1).
- **incl_pos** (list, optional) - A list of Part-of-Speech tags to include in the term extraction. Defaults to None.
- **freq_min** (int, optional) - The minimum frequency a term must have to be included. Defaults to 1.
- **return_as_table** (bool, optional) - If True, returns a pandas DataFrame. If False, returns raw spaCy spans. Defaults to True.

### Returns
- pandas.DataFrame or list - A table of extracted terms with their POS tags, rank, and frequency, or a list of raw spaCy spans.
```

--------------------------------

### Extract Terms with Length Constraints

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Extracts terms from a sentence, specifying the minimum and maximum length of the terms using the span_range option. Requires the TermExtractor class.

```python
>>> extractor = TermExtractor(en_sentence)  
>>> terms = extractor.extract_terms(span_range=(2,3))
>>> print(terms[:10])
```

--------------------------------

### Extract Terms with Part-of-Speech Tags (Python)

Source: https://github.com/luismond/tm2tb/blob/main/README.md

Use this snippet to extract terms from a sentence, filtering by specified part-of-speech tags. Requires the TermExtractor class.

```python
>>> extractor = TermExtractor(en_sentence)
>>> terms = extractor.extract_terms(incl_pos=['ADJ', 'NOUN'])
>>> print(terms[:10])
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.