### Installation

Source: https://context7.com/datamade/probablepeople/llms.txt

Install the probablepeople library using pip.

```APIDOC
## Installation

Install probablepeople using pip.

```bash
pip install probablepeople
```
```

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

### Build and test development code

Source: https://github.com/datamade/probablepeople/blob/main/README.md

Clone the repository, install the package in editable mode, and run tests. This is for developers who want to work with the source code.

```bash
git clone https://github.com/datamade/probablepeople.git
cd probablepeople
pip install -e .
pytest
```

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

### Install probablepeople

Source: https://github.com/datamade/probablepeople/blob/main/docs/index.md

Install the probablepeople library using pip.

```bash
pip install probablepeople
```

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

### Example Usage of Name Parsing with Labels

Source: https://context7.com/datamade/probablepeople/llms.txt

Demonstrates `pp.parse()` with different name types, showing how labels are assigned to components. This includes person names, corporations, and 'aka' (also known as) entries.

```python
import probablepeople as pp

# Person with various components
result = pp.parse('Dr. John Michael Smith III')
# Labels: PrefixOther, GivenName, MiddleName, Surname, SuffixGenerational
```

```python
# Corporation with legal type
result = pp.parse('Apple Computer Inc')
# Labels: CorporationName, CorporationName, CorporationLegalType
```

```python
# AKA (Also Known As) handling
result = pp.parse('John Smith aka Johnny')
# Labels may include: GivenName, Surname, AKA, OtherGivenName
```

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

### Label Raw Data for Training

Source: https://github.com/datamade/probablepeople/blob/main/README.md

Use this command to start a console labeling task for raw CSV data. Specify the input CSV file and the appropriate XML output file for training data (e.g., company_labeled.xml for organizations).

```bash
parserator label [infile] [outfile] probablepeople
```

```bash
parserator label my_companies.csv name_data/labeled/company_labeled.xml probablepeople
```

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

### Tag name string with labels and type

Source: https://github.com/datamade/probablepeople/blob/main/docs/index.md

Use the `tag` method to get an OrderedDict of labeled components and the string type (Person, Household, or Corporation). This method groups similar labels.

```python
>>> import probablepeople
>>> probablepeople.tag('Mr George "Gob" Bluth II')
(OrderedDict([
('PrefixMarital', 'Mr'),
('GivenName', 'George'),
('Nickname', '"Gob"'),
('Surname', 'Bluth'),
('SuffixGenerational', 'II')]),
'Person')
```

```python
>>> probablepeople.tag('Lucille & George Bluth')
(OrderedDict([
('GivenName', 'Lucille'),
('And', '&'),
('SecondGivenName', 'George'),
('Surname', 'Bluth')]),
'Household')
```

```python
>>> probablepeople.tag('Sitwell Housing Inc')
(OrderedDict([
('CorporationName', 'Sitwell Housing'),
('CorporationLegalType', 'Inc')]),
'Corporation')
```

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

### Training Custom Name Parsing Models with parserator

Source: https://context7.com/datamade/probablepeople/llms.txt

These bash commands illustrate how to use the `parserator` tool to label new training data and train custom person or company-specific models. This improves accuracy for specific name formats.

```bash
# Label new training data from a CSV file
# This starts an interactive console labeling session
parserator label my_names.csv name_data/labeled/person_labeled.xml probablepeople
```

```bash
# Train the generic model (both person and company names)
parserator train name_data/labeled/person_labeled.xml,name_data/labeled/company_labeled.xml probablepeople --modelfile=generic
```

```bash
# Train person-only model
parserator train name_data/labeled/person_labeled.xml probablepeople --modelfile=person
```

```bash
# Train company-only model
parserator train name_data/labeled/company_labeled.xml probablepeople --modelfile=company
```

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

### Parse name and company strings

Source: https://github.com/datamade/probablepeople/blob/main/README.md

Use the `parse` method to split strings into components and label each component. This method is useful for detailed analysis of string structures.

```python
import probablepeople as pp
name_str='Mr George "Gob" Bluth II'
corp_str='Sitwell Housing Inc'

# The parse method will split your string into components, and label each component.
pp.parse(name_str) # expected output: [('Mr', 'PrefixMarital'), ('George', 'GivenName'), ('"Gob"', 'Nickname'), ('Bluth', 'Surname'), ('II', 'SuffixGenerational')]
pp.parse(corp_str) # expected output: [('Sitwell', 'CorporationName'), ('Housing', 'CorporationName'), ('Inc', 'CorporationLegalType')]
```

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

### Parse Person Name with Prefix, Nickname, and Suffix

Source: https://context7.com/datamade/probablepeople/llms.txt

Use the `parse()` function to split a person's name into tokens and label each with its component type, including prefixes, nicknames, and suffixes.

```python
import probablepeople as pp

# Parse a person name with prefix, nickname, and suffix
result = pp.parse('Mr George "Gob" Bluth II')
print(result)
# Output: [('Mr', 'PrefixMarital'), ('George', 'GivenName'), ('"Gob"', 'Nickname'), ('Bluth', 'Surname'), ('II', 'SuffixGenerational')]
```

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

### Fallback to parse() when tag() fails

Source: https://context7.com/datamade/probablepeople/llms.txt

Demonstrates using `pp.parse()` as a fallback mechanism when `pp.tag()` encounters a `RepeatedLabelError`. This ensures that name parsing always succeeds.

```python
try:
    tagged, name_type = pp.tag(complex_name)
except pp.RepeatedLabelError as e:
    # Fall back to parse() which always succeeds
    components = pp.parse(complex_name)
    print(f"Parsed components: {components}")
```

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

### parse() - Parse String into Labeled Components

Source: https://context7.com/datamade/probablepeople/llms.txt

The `parse()` function splits a name or company string into individual tokens and labels each token with its component type. It returns a list of tuples containing (token, label) pairs, preserving the original order. You can optionally specify the parsing model using the `type` parameter.

```APIDOC
## parse() - Parse String into Labeled Components

The `parse()` function splits a name or company string into individual tokens and labels each token with its component type. It returns a list of tuples containing (token, label) pairs, preserving the original order.

```python
import probablepeople as pp

# Parse a person name with prefix, nickname, and suffix
result = pp.parse('Mr George "Gob" Bluth II')
print(result)
# Output: [('Mr', 'PrefixMarital'), ('George', 'GivenName'), ('"Gob"', 'Nickname'), ('Bluth', 'Surname'), ('II', 'SuffixGenerational')]

# Parse a household name with multiple people
result = pp.parse('Lucille & George Bluth')
print(result)
# Output: [('Lucille', 'GivenName'), ('&', 'And'), ('George', 'GivenName'), ('Bluth', 'Surname')]

# Parse a corporation name
result = pp.parse('Sitwell Housing Inc')
print(result)
# Output: [('Sitwell', 'CorporationName'), ('Housing', 'CorporationName'), ('Inc', 'CorporationLegalType')]

# Use type parameter to specify parsing model
person_result = pp.parse('John Smith Jr', type='person')
company_result = pp.parse('Acme Corporation LLC', type='company')
```
```

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

### Tag name and company strings

Source: https://github.com/datamade/probablepeople/blob/main/README.md

Use the `tag` method for a smarter parsing approach that merges consecutive components, strips commas, and returns a string type. This is useful for obtaining a more summarized and categorized output.

```python
import probablepeople as pp
name_str='Mr George "Gob" Bluth II'
corp_str='Sitwell Housing Inc'

# The tag method will try to be a little smarter
# it will merge consecutive components, strip commas, & return a string type
pp.tag(name_str) # expected output: (OrderedDict([('PrefixMarital', 'Mr'), ('GivenName', 'George'), ('Nickname', '"Gob"'), ('Surname', 'Bluth'), ('SuffixGenerational', 'II')]), 'Person')
pp.tag(corp_str) # expected output: (OrderedDict([('CorporationName', 'Sitwell Housing'), ('CorporationLegalType', 'Inc')]), 'Corporation')
```

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

### Parse name string into components

Source: https://github.com/datamade/probablepeople/blob/main/docs/index.md

Use the `parse` method to split a string into labeled components. This is useful for breaking down unstructured names.

```python
>>> import probablepeople
>>> probablepeople.parse('Mr George "Gob" Bluth II')
[('Mr', 'PrefixMarital'),
('George', 'GivenName'),
('"Gob"', 'Nickname'),
('Bluth', 'Surname'),
('II', 'SuffixGenerational')]
```

```python
>>> probablepeople.parse('Lucille & George Bluth')
[('Lucille', 'GivenName'),
('&', 'And'),
('George', 'GivenName'),
('Bluth', 'Surname')]
```

```python
>>> probablepeople.parse('Sitwell Housing Inc')
[('Sitwell', 'CorporationName'),
('Housing', 'CorporationName'),
('Inc', 'CorporationLegalType')]
```

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

### Retrain Probable People Model

Source: https://github.com/datamade/probablepeople/blob/main/README.md

Retrain the probablepeople model after adding new training data. Multiple labeled files can be specified by separating them with commas. The --modelfile flag can be used to specify the type of model to train (generic, person, or company).

```bash
parserator train [traindata] probablepeople
```

```bash
parserator train name_data/labeled/person_labeled.xml,name_data/labeled/company_labeled.xml probablepeople --modelfile=generic
```

```bash
parserator train name_data/labeled/person_labeled.xml probablepeople --modelfile=person
```

```bash
parserator train name_data/labeled/company_labeled.xml probablepeople --modelfile=company
```

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

### tag() - Parse and Merge into Dictionary

Source: https://context7.com/datamade/probablepeople/llms.txt

The `tag()` function parses the string and returns an OrderedDict with distinct labels as keys and concatenated values, along with a type string indicating whether the input is a "Person", "Household", or "Corporation". Consecutive `CorporationName` tokens are merged.

```APIDOC
## tag() - Parse and Merge into Dictionary

The `tag()` function parses the string and returns an OrderedDict with distinct labels as keys and concatenated values, along with a type string indicating whether the input is a "Person", "Household", or "Corporation".

```python
import probablepeople as pp

# Tag a person name - returns OrderedDict and type
tagged, name_type = pp.tag('Mr George "Gob" Bluth II')
print(name_type)  # Output: 'Person'
print(tagged)
# Output: OrderedDict([('PrefixMarital', 'Mr'), ('GivenName', 'George'), ('Nickname', '"Gob"'), ('Surname', 'Bluth'), ('SuffixGenerational', 'II')])

# Tag a household (multiple people joined with &)
tagged, name_type = pp.tag('Lucille & George Bluth')
print(name_type)  # Output: 'Household'
print(tagged)
# Output: OrderedDict([('GivenName', 'Lucille'), ('And', '&'), ('SecondGivenName', 'George'), ('Surname', 'Bluth')])

# Tag a corporation - consecutive CorporationName tokens are merged
tagged, name_type = pp.tag('Sitwell Housing Inc')
print(name_type)  # Output: 'Corporation'
print(tagged)
# Output: OrderedDict([('CorporationName', 'Sitwell Housing'), ('CorporationLegalType', 'Inc')])

# Access individual components from tagged result
tagged, _ = pp.tag('Dr. Jane Elizabeth Smith, PhD')
first_name = tagged.get('GivenName')
last_name = tagged.get('Surname')
print(f"First: {first_name}, Last: {last_name}")
```
```

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

### Using Trained Custom Models with probablepeople

Source: https://context7.com/datamade/probablepeople/llms.txt

After training custom models using `parserator`, you can specify the model type ('person' or 'company') when calling `pp.parse()` or `pp.tag()` for optimized results. The default model is 'generic'.

```python
import probablepeople as pp

# Default (generic) model - handles both persons and companies
result = pp.parse('John Smith')
```

```python
# Person-specific model - optimized for person names
result = pp.parse('John Smith', type='person')
```

```python
# Company-specific model - optimized for company names
result = pp.parse('Acme Industries LLC', type='company')
```

```python
# The tag() method also accepts the type parameter
tagged, name_type = pp.tag('Jane Doe', type='person')
tagged, name_type = pp.tag('DataMade Inc', type='company')
```

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

### Available Name Component Labels

Source: https://context7.com/datamade/probablepeople/llms.txt

The `LABELS` constant provides a list of all supported labels for identifying name and company components. These labels are used internally by the parsing functions.

```python
from probablepeople import LABELS

# Available labels for parsing
print(LABELS)
# Output: ['PrefixMarital', 'PrefixOther', 'GivenName', 'FirstInitial',
#          'MiddleName', 'MiddleInitial', 'Surname', 'LastInitial',
#          'SuffixGenerational', 'SuffixOther', 'Nickname', 'And',
#          'CorporationName', 'CorporationNameOrganization',
#          'CorporationNameAndCompany', 'CorporationNameBranchType',
#          'CorporationNameBranchIdentifier', 'CorporationCommitteeType',
#          'CorporationLegalType', 'ShortForm', 'ProxyFor', 'AKA']
```

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

### Tag Person Name

Source: https://context7.com/datamade/probablepeople/llms.txt

Use the `tag()` function to parse a person's name and return an OrderedDict of labeled components and the identified name type.

```python
import probablepeople as pp

# Tag a person name - returns OrderedDict and type
tagged, name_type = pp.tag('Mr George "Gob" Bluth II')
print(name_type)  # Output: 'Person'
print(tagged)
# Output: OrderedDict([('PrefixMarital', 'Mr'), ('GivenName', 'George'), ('Nickname', '"Gob"'), ('Surname', 'Bluth'), ('SuffixGenerational', 'II')])
```

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

### Specify Parsing Model with type parameter

Source: https://context7.com/datamade/probablepeople/llms.txt

Use the `type` parameter in the `parse()` function to specify whether to use the 'person' or 'company' parsing model.

```python
import probablepeople as pp

# Use type parameter to specify parsing model
person_result = pp.parse('John Smith Jr', type='person')
company_result = pp.parse('Acme Corporation LLC', type='company')
```

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

### Tokenize Name Strings with probablepeople

Source: https://context7.com/datamade/probablepeople/llms.txt

The `tokenize()` function splits raw strings into tokens for name parsing. It handles punctuation, abbreviations, quotes, ampersands, and care-of notation. Ensure `probablepeople` is imported.

```python
from probablepeople import tokenize

# Basic tokenization
tokens = tokenize('Bob Belcher')
print(tokens)  # Output: ['Bob', 'Belcher']
```

```python
# Handles trailing punctuation
tokens = tokenize('belcher,bob')
print(tokens)  # Output: ['belcher,', 'bob']
```

```python
# Preserves hyphenated names
tokens = tokenize('Mary Anne Smith-Jones')
print(tokens)  # Output: ['Mary', 'Anne', 'Smith-Jones']
```

```python
# Handles abbreviations with periods
tokens = tokenize('Robert B. Smith Jr.')
print(tokens)  # Output: ['Robert', 'B.', 'Smith', 'Jr.']
```

```python
# Handles nicknames in quotes or parentheses
tokens = tokenize('Robert "Bob" Belcher')
print(tokens)  # Output: ['Robert', '"Bob"', 'Belcher']
```

```python
tokens = tokenize('Robert (Bob) Belcher')
print(tokens)  # Output: ['Robert', '(Bob)', 'Belcher']
```

```python
# Handles ampersand for couples
tokens = tokenize('Mr & Mrs Smith')
print(tokens)  # Output: ['Mr', '&', 'Mrs', 'Smith']
```

```python
# Handles care-of notation
tokens = tokenize('John Smith c/o Jane Doe')
print(tokens)  # Output: ['John', 'Smith', 'c/o', 'Jane', 'Doe']
```

```python
# Multiple spaces are normalized
tokens = tokenize('foo  bar')
print(tokens)  # Output: ['foo', 'bar']
```

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

### Parse Corporation Name

Source: https://context7.com/datamade/probablepeople/llms.txt

Use the `parse()` function to split a corporation name into tokens and label them with their respective corporation-related types.

```python
import probablepeople as pp

# Parse a corporation name
result = pp.parse('Sitwell Housing Inc')
print(result)
# Output: [('Sitwell', 'CorporationName'), ('Housing', 'CorporationName'), ('Inc', 'CorporationLegalType')]
```

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

### Access Individual Components from Tagged Result

Source: https://context7.com/datamade/probablepeople/llms.txt

Access individual components from the OrderedDict returned by the `tag()` function using dictionary methods like `.get()`.

```python
import probablepeople as pp

# Access individual components from tagged result
tagged, _ = pp.tag('Dr. Jane Elizabeth Smith, PhD')
first_name = tagged.get('GivenName')
last_name = tagged.get('Surname')
print(f"First: {first_name}, Last: {last_name}")
```

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

### RepeatedLabelError - Handle Parsing Ambiguities

Source: https://context7.com/datamade/probablepeople/llms.txt

When the `tag()` method encounters multiple non-consecutive tokens with the same label that cannot be merged, it raises a `RepeatedLabelError`. This typically indicates an invalid input or labeling uncertainty. The error provides access to both the original string and the parsed output for custom handling.

```APIDOC
## RepeatedLabelError - Handle Parsing Ambiguities

When the `tag()` method encounters multiple non-consecutive tokens with the same label that cannot be merged, it raises a `RepeatedLabelError`. This typically indicates an invalid input or labeling uncertainty. The error provides access to both the original string and the parsed output for custom handling.

```python
import probablepeople as pp

def safe_tag(name_string):
    """Parse a name with custom error handling for ambiguous cases."""
    try:
        tagged, name_type = pp.tag(name_string)
        return {
            'success': True,
            'tagged': dict(tagged),
            'type': name_type
        }
    except pp.RepeatedLabelError as e:
        # Access the original input
        original = e.original_string
        # Access the parse() output for inspection
        parsed = e.parsed_string
        return {
            'success': False,
            'original': original,
            'parsed': parsed,
            'message': f"Could not tag: ambiguous labels in '{original}'"
        }

# Example with potential ambiguity
result = safe_tag('Bob Belcher')
print(result)
# Output: {'success': True, 'tagged': {'GivenName': 'Bob', 'Surname': 'Belcher'}, 'type': 'Person'}
```
```

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

### Handle RepeatedLabelError with Safe Tagging Function

Source: https://context7.com/datamade/probablepeople/llms.txt

Implement a `safe_tag` function to handle `RepeatedLabelError` during parsing, returning custom error information including the original and parsed strings.

```python
import probablepeople as pp

def safe_tag(name_string):
    """Parse a name with custom error handling for ambiguous cases."""
    try:
        tagged, name_type = pp.tag(name_string)
        return {
            'success': True,
            'tagged': dict(tagged),
            'type': name_type
        }
    except pp.RepeatedLabelError as e:
        # Access the original input
        original = e.original_string
        # Access the parse() output for inspection
        parsed = e.parsed_string
        return {
            'success': False,
            'original': original,
            'parsed': parsed,
            'message': f"Could not tag: ambiguous labels in '{original}'"
        }

# Example with potential ambiguity
result = safe_tag('Bob Belcher')
print(result)
# Output: {'success': True, 'tagged': {'GivenName': 'Bob', 'Surname': 'Belcher'}, 'type': 'Person'}
```

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

### Handle RepeatedLabelError

Source: https://github.com/datamade/probablepeople/blob/main/docs/index.md

Catch and handle `RepeatedLabelError` which occurs when multiple parts of a name share the same label. Use `e.parsed_string` and `e.original_string` for custom error handling.

```python
try:
    tagged_name, name_type = probablepeople.tag(string)
except probablepeople.RepeatedLabelError as e :
    some_special_instructions(e.parsed_string, e.original_string)
```

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

### Tag Household Name

Source: https://context7.com/datamade/probablepeople/llms.txt

Use the `tag()` function to parse a household name (multiple people joined by '&') and return an OrderedDict of labeled components and the identified name type.

```python
import probablepeople as pp

# Tag a household (multiple people joined with &)
tagged, name_type = pp.tag('Lucille & George Bluth')
print(name_type)  # Output: 'Household'
print(tagged)
# Output: OrderedDict([('GivenName', 'Lucille'), ('And', '&'), ('SecondGivenName', 'George'), ('Surname', 'Bluth')])
```

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

### Tag Corporation Name

Source: https://context7.com/datamade/probablepeople/llms.txt

Use the `tag()` function to parse a corporation name, merging consecutive 'CorporationName' tokens, and return an OrderedDict and the identified name type.

```python
import probablepeople as pp

# Tag a corporation - consecutive CorporationName tokens are merged
tagged, name_type = pp.tag('Sitwell Housing Inc')
print(name_type)  # Output: 'Corporation'
print(tagged)
# Output: OrderedDict([('CorporationName', 'Sitwell Housing'), ('CorporationLegalType', 'Inc')])
```

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

### Parse Household Name with Multiple People

Source: https://context7.com/datamade/probablepeople/llms.txt

Use the `parse()` function to split a household name string containing multiple people joined by '&' into labeled tokens.

```python
import probablepeople as pp

# Parse a household name with multiple people
result = pp.parse('Lucille & George Bluth')
print(result)
# Output: [('Lucille', 'GivenName'), ('&', 'And'), ('George', 'GivenName'), ('Bluth', 'Surname')]
```

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