# Entity Linker Client
[](https://badge.fury.io/py/entity-linker-client)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A Python client library for the Entity Linker service that provides intelligent entity matching and linking capabilities. This library enables developers to easily integrate powerful entity resolution features into their applications.
## Features
- **Intelligent Entity Matching**: Supports multiple matching strategies including lexical similarity, semantic similarity, and exact matching
- **Flexible Configuration**: Customizable matching rules and thresholds
- **Batch Operations**: Efficient batch processing for large datasets
- **Type Safety**: Full type annotations for better development experience
- **Simple API**: Clean and intuitive interface for easy integration
## Installation
Install the package using pip:
```bash
pip install entity-linker-client
```
## Quick Start
Here's a simple example to get you started:
```python
from entity_linker_client import EntityLinker
# Initialize the client
linker = EntityLinker(
base_url="http://localhost:6000",
source_columns=["name", "address", "phone"],
target_columns=["business_name", "business_address", "contact_number"]
)
# Add some entities
entities = [
{
"canonical_name": "Acme Corporation",
"aliases": ["Acme Corp", "Acme Inc"],
"metadata": {
"address": "123 Business Ave",
"phone": "+1-555-0123"
}
}
]
added_entities = linker.add_entities_batch(entities)
print(f"Added {len(added_entities)} entities")
# Link a new entity
entity_to_link = {
"canonical_name": "Acme Corp",
"aliases": [],
"metadata": {
"address": "123 Business Avenue",
"phone": "+1-555-0123"
}
}
result = linker.link_entity(entity_to_link)
if result.get("linked_entity_id"):
print(f"Found match: {result['linked_entity_id']}")
else:
print("No match found")
```
## Configuration
### Basic Configuration
The simplest way to create a linker is by providing source and target columns:
```python
from entity_linker_client import EntityLinker
linker = EntityLinker(
base_url="http://localhost:6000",
source_columns=["name", "industry", "location"],
target_columns=["company_name", "sector", "address"]
)
```
### Advanced Configuration
For more control, you can provide a custom configuration:
```python
from entity_linker_client import (
EntityLinker, EntityLinkingConfig, OrCondition,
FieldCondition, MatchCondition, MatchType
)
# Create custom configuration
config = EntityLinkingConfig(
quick_creation_config=OrCondition(
conditions=[
FieldCondition(
field="canonical_name",
condition=MatchCondition(
match_type=MatchType.LEXICAL_SIMILARITY,
threshold=80
)
)
]
),
# ... other configurations
)
linker = EntityLinker(base_url="http://localhost:6000", config=config)
```
## API Reference
### EntityLinker Class
The main class for interacting with the Entity Linker service.
#### Methods
- `add_entity(entity_data)`: Add a single entity
- `add_entities_batch(entities_data)`: Add multiple entities in batch
- `get_entity(entity_id)`: Retrieve an entity by ID
- `modify_entity(entity_id, entity_data)`: Update an existing entity
- `delete_entity(entity_id)`: Delete an entity
- `link_entity(entity_data, add_entity=False)`: Find matching entities
- `link_entity_with_id(entity_id)`: Link using an existing entity ID
- `get_info()`: Get linker information
- `update_config(config)`: Update linker configuration
- `delete_linker()`: Delete the linker instance
#### Static Methods
- `list_available_linkers(base_url)`: List all available linkers
- `get_linker_info(linker_id, base_url)`: Get information about a specific linker
- `generate_config(initial_config, source_columns, target_columns, base_url)`: Generate configuration
### Configuration Classes
#### EntityLinkingConfig
Main configuration class containing:
- `quick_creation_config`: Configuration for quick entity creation
- `quick_linking_config`: Configuration for quick entity linking
- `llm_linking_config`: Configuration for LLM-based linking
- `llm_top_k`: Number of top results for LLM linking
#### MatchType Enum
Available matching strategies:
- `STRICT_MATCH`: Exact string matching
- `LEXICAL_SIMILARITY`: Token-based similarity
- `SEMANTIC_SIMILARITY`: Embedding-based similarity
- `DICT_MATCH`: Dictionary field matching
## Examples
### Working with Entities
```python
# Add a single entity
entity = {
"canonical_name": "OpenAI Inc",
"aliases": ["OpenAI", "OpenAI LP"],
"metadata": {
"industry": "AI Research",
"founded": "2015"
}
}
added_entity = linker.add_entity(entity)
entity_id = added_entity["id"]
# Modify the entity
updated_data = {
"canonical_name": "OpenAI Inc",
"aliases": ["OpenAI", "OpenAI LP", "OpenAI L.P."],
"metadata": {
"industry": "Artificial Intelligence",
"founded": "2015",
"headquarters": "San Francisco"
}
}
modified_entity = linker.modify_entity(entity_id, updated_data)
```
### Batch Operations
```python
# Add multiple entities at once
companies = [
{
"canonical_name": "Google LLC",
"aliases": ["Google", "Alphabet Inc"],
"metadata": {"industry": "Technology"}
},
{
"canonical_name": "Microsoft Corporation",
"aliases": ["Microsoft", "MSFT"],
"metadata": {"industry": "Technology"}
}
]
batch_result = linker.add_entities_batch(companies)
print(f"Added {len(batch_result)} companies")
```
### Entity Linking
```python
# Try to link a potentially matching entity
candidate = {
"canonical_name": "Alphabet",
"aliases": ["Google Inc"],
"metadata": {"industry": "Tech"}
}
# Link without adding to database
link_result = linker.link_entity(candidate, add_entity=False)
if link_result.get("linked_entity_id"):
print(f"Found existing entity: {link_result['linked_entity_id']}")
else:
# Add as new entity if no match found
link_result = linker.link_entity(candidate, add_entity=True)
print(f"Created new entity: {link_result.get('linked_entity_id', 'Failed')}")
```
## Environment Variables
You can configure the client using environment variables:
```bash
export ENTITY_LINKER_BASE_URL="http://your-entity-linker-service:6000"
```
## Error Handling
The client includes proper error handling for common scenarios:
```python
from entity_linker_client import EntityLinker
import httpx
try:
linker = EntityLinker(base_url="http://localhost:6000")
entity = linker.get_entity("non-existent-id")
except httpx.HTTPStatusError as e:
print(f"HTTP error: {e.response.status_code}")
except httpx.RequestError as e:
print(f"Request error: {e}")
except ValueError as e:
print(f"Configuration error: {e}")
```
## Requirements
- Python 3.8 or higher
- httpx >= 0.24.0
- python-dotenv >= 0.19.0
## Development
To contribute to this project:
1. Clone the repository
2. Install development dependencies: `pip install -e .[dev]`
3. Run tests: `pytest`
4. Format code: `black .`
5. Check types: `mypy .`
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
For support and questions:
- Email: support@godel-ai.com
- Issues: [GitHub Issues](https://github.com/godel-ai/entity-linker-client/issues)
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
Raw data
{
"_id": null,
"home_page": null,
"name": "entity-linker-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Godel Backend Team <support@godel-ai.com>",
"keywords": "entity-linking, data-matching, nlp, entity-resolution, record-linkage, fuzzy-matching, semantic-similarity",
"author": null,
"author_email": "Godel Backend Team <support@godel-ai.com>",
"download_url": "https://files.pythonhosted.org/packages/eb/fe/f3ff56e93dc4b2d780682ecf8c1cb9a05ec092bdc49ceba893ff0e270aab/entity_linker_client-1.0.2.tar.gz",
"platform": null,
"description": "# Entity Linker Client\r\n\r\n[](https://badge.fury.io/py/entity-linker-client)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nA Python client library for the Entity Linker service that provides intelligent entity matching and linking capabilities. This library enables developers to easily integrate powerful entity resolution features into their applications.\r\n\r\n## Features\r\n\r\n- **Intelligent Entity Matching**: Supports multiple matching strategies including lexical similarity, semantic similarity, and exact matching\r\n- **Flexible Configuration**: Customizable matching rules and thresholds\r\n- **Batch Operations**: Efficient batch processing for large datasets\r\n- **Type Safety**: Full type annotations for better development experience\r\n- **Simple API**: Clean and intuitive interface for easy integration\r\n\r\n## Installation\r\n\r\nInstall the package using pip:\r\n\r\n```bash\r\npip install entity-linker-client\r\n```\r\n\r\n## Quick Start\r\n\r\nHere's a simple example to get you started:\r\n\r\n```python\r\nfrom entity_linker_client import EntityLinker\r\n\r\n# Initialize the client\r\nlinker = EntityLinker(\r\n base_url=\"http://localhost:6000\",\r\n source_columns=[\"name\", \"address\", \"phone\"],\r\n target_columns=[\"business_name\", \"business_address\", \"contact_number\"]\r\n)\r\n\r\n# Add some entities\r\nentities = [\r\n {\r\n \"canonical_name\": \"Acme Corporation\",\r\n \"aliases\": [\"Acme Corp\", \"Acme Inc\"],\r\n \"metadata\": {\r\n \"address\": \"123 Business Ave\",\r\n \"phone\": \"+1-555-0123\"\r\n }\r\n }\r\n]\r\n\r\nadded_entities = linker.add_entities_batch(entities)\r\nprint(f\"Added {len(added_entities)} entities\")\r\n\r\n# Link a new entity\r\nentity_to_link = {\r\n \"canonical_name\": \"Acme Corp\",\r\n \"aliases\": [],\r\n \"metadata\": {\r\n \"address\": \"123 Business Avenue\",\r\n \"phone\": \"+1-555-0123\"\r\n }\r\n}\r\n\r\nresult = linker.link_entity(entity_to_link)\r\nif result.get(\"linked_entity_id\"):\r\n print(f\"Found match: {result['linked_entity_id']}\")\r\nelse:\r\n print(\"No match found\")\r\n```\r\n\r\n## Configuration\r\n\r\n### Basic Configuration\r\n\r\nThe simplest way to create a linker is by providing source and target columns:\r\n\r\n```python\r\nfrom entity_linker_client import EntityLinker\r\n\r\nlinker = EntityLinker(\r\n base_url=\"http://localhost:6000\",\r\n source_columns=[\"name\", \"industry\", \"location\"],\r\n target_columns=[\"company_name\", \"sector\", \"address\"]\r\n)\r\n```\r\n\r\n### Advanced Configuration\r\n\r\nFor more control, you can provide a custom configuration:\r\n\r\n```python\r\nfrom entity_linker_client import (\r\n EntityLinker, EntityLinkingConfig, OrCondition, \r\n FieldCondition, MatchCondition, MatchType\r\n)\r\n\r\n# Create custom configuration\r\nconfig = EntityLinkingConfig(\r\n quick_creation_config=OrCondition(\r\n conditions=[\r\n FieldCondition(\r\n field=\"canonical_name\",\r\n condition=MatchCondition(\r\n match_type=MatchType.LEXICAL_SIMILARITY,\r\n threshold=80\r\n )\r\n )\r\n ]\r\n ),\r\n # ... other configurations\r\n)\r\n\r\nlinker = EntityLinker(base_url=\"http://localhost:6000\", config=config)\r\n```\r\n\r\n## API Reference\r\n\r\n### EntityLinker Class\r\n\r\nThe main class for interacting with the Entity Linker service.\r\n\r\n#### Methods\r\n\r\n- `add_entity(entity_data)`: Add a single entity\r\n- `add_entities_batch(entities_data)`: Add multiple entities in batch\r\n- `get_entity(entity_id)`: Retrieve an entity by ID\r\n- `modify_entity(entity_id, entity_data)`: Update an existing entity\r\n- `delete_entity(entity_id)`: Delete an entity\r\n- `link_entity(entity_data, add_entity=False)`: Find matching entities\r\n- `link_entity_with_id(entity_id)`: Link using an existing entity ID\r\n- `get_info()`: Get linker information\r\n- `update_config(config)`: Update linker configuration\r\n- `delete_linker()`: Delete the linker instance\r\n\r\n#### Static Methods\r\n\r\n- `list_available_linkers(base_url)`: List all available linkers\r\n- `get_linker_info(linker_id, base_url)`: Get information about a specific linker\r\n- `generate_config(initial_config, source_columns, target_columns, base_url)`: Generate configuration\r\n\r\n### Configuration Classes\r\n\r\n#### EntityLinkingConfig\r\n\r\nMain configuration class containing:\r\n- `quick_creation_config`: Configuration for quick entity creation\r\n- `quick_linking_config`: Configuration for quick entity linking \r\n- `llm_linking_config`: Configuration for LLM-based linking\r\n- `llm_top_k`: Number of top results for LLM linking\r\n\r\n#### MatchType Enum\r\n\r\nAvailable matching strategies:\r\n- `STRICT_MATCH`: Exact string matching\r\n- `LEXICAL_SIMILARITY`: Token-based similarity\r\n- `SEMANTIC_SIMILARITY`: Embedding-based similarity\r\n- `DICT_MATCH`: Dictionary field matching\r\n\r\n## Examples\r\n\r\n### Working with Entities\r\n\r\n```python\r\n# Add a single entity\r\nentity = {\r\n \"canonical_name\": \"OpenAI Inc\",\r\n \"aliases\": [\"OpenAI\", \"OpenAI LP\"],\r\n \"metadata\": {\r\n \"industry\": \"AI Research\",\r\n \"founded\": \"2015\"\r\n }\r\n}\r\n\r\nadded_entity = linker.add_entity(entity)\r\nentity_id = added_entity[\"id\"]\r\n\r\n# Modify the entity\r\nupdated_data = {\r\n \"canonical_name\": \"OpenAI Inc\",\r\n \"aliases\": [\"OpenAI\", \"OpenAI LP\", \"OpenAI L.P.\"],\r\n \"metadata\": {\r\n \"industry\": \"Artificial Intelligence\",\r\n \"founded\": \"2015\",\r\n \"headquarters\": \"San Francisco\"\r\n }\r\n}\r\n\r\nmodified_entity = linker.modify_entity(entity_id, updated_data)\r\n```\r\n\r\n### Batch Operations\r\n\r\n```python\r\n# Add multiple entities at once\r\ncompanies = [\r\n {\r\n \"canonical_name\": \"Google LLC\",\r\n \"aliases\": [\"Google\", \"Alphabet Inc\"],\r\n \"metadata\": {\"industry\": \"Technology\"}\r\n },\r\n {\r\n \"canonical_name\": \"Microsoft Corporation\", \r\n \"aliases\": [\"Microsoft\", \"MSFT\"],\r\n \"metadata\": {\"industry\": \"Technology\"}\r\n }\r\n]\r\n\r\nbatch_result = linker.add_entities_batch(companies)\r\nprint(f\"Added {len(batch_result)} companies\")\r\n```\r\n\r\n### Entity Linking\r\n\r\n```python\r\n# Try to link a potentially matching entity\r\ncandidate = {\r\n \"canonical_name\": \"Alphabet\",\r\n \"aliases\": [\"Google Inc\"],\r\n \"metadata\": {\"industry\": \"Tech\"}\r\n}\r\n\r\n# Link without adding to database\r\nlink_result = linker.link_entity(candidate, add_entity=False)\r\n\r\nif link_result.get(\"linked_entity_id\"):\r\n print(f\"Found existing entity: {link_result['linked_entity_id']}\")\r\nelse:\r\n # Add as new entity if no match found\r\n link_result = linker.link_entity(candidate, add_entity=True)\r\n print(f\"Created new entity: {link_result.get('linked_entity_id', 'Failed')}\")\r\n```\r\n\r\n## Environment Variables\r\n\r\nYou can configure the client using environment variables:\r\n\r\n```bash\r\nexport ENTITY_LINKER_BASE_URL=\"http://your-entity-linker-service:6000\"\r\n```\r\n\r\n## Error Handling\r\n\r\nThe client includes proper error handling for common scenarios:\r\n\r\n```python\r\nfrom entity_linker_client import EntityLinker\r\nimport httpx\r\n\r\ntry:\r\n linker = EntityLinker(base_url=\"http://localhost:6000\")\r\n entity = linker.get_entity(\"non-existent-id\")\r\nexcept httpx.HTTPStatusError as e:\r\n print(f\"HTTP error: {e.response.status_code}\")\r\nexcept httpx.RequestError as e:\r\n print(f\"Request error: {e}\")\r\nexcept ValueError as e:\r\n print(f\"Configuration error: {e}\")\r\n```\r\n\r\n## Requirements\r\n\r\n- Python 3.8 or higher\r\n- httpx >= 0.24.0\r\n- python-dotenv >= 0.19.0\r\n\r\n## Development\r\n\r\nTo contribute to this project:\r\n\r\n1. Clone the repository\r\n2. Install development dependencies: `pip install -e .[dev]`\r\n3. Run tests: `pytest`\r\n4. Format code: `black .`\r\n5. Check types: `mypy .`\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n## Support\r\n\r\nFor support and questions:\r\n- Email: support@godel-ai.com\r\n- Issues: [GitHub Issues](https://github.com/godel-ai/entity-linker-client/issues)\r\n\r\n## Changelog\r\n\r\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python client for the Entity Linker service - intelligent entity matching and linking",
"version": "1.0.2",
"project_urls": {
"Changelog": "https://github.com/godel-ai/entity-linker-client/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/godel-ai/entity-linker-client#readme",
"Homepage": "https://github.com/godel-ai/entity-linker-client",
"Issues": "https://github.com/godel-ai/entity-linker-client/issues",
"Repository": "https://github.com/godel-ai/entity-linker-client"
},
"split_keywords": [
"entity-linking",
" data-matching",
" nlp",
" entity-resolution",
" record-linkage",
" fuzzy-matching",
" semantic-similarity"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "56dab000cafac4bd4a06ecac31047609686ce9c67c122a2cf9d10514abc00afa",
"md5": "517900181f2cbfef728ead81e972d1fc",
"sha256": "b420ee98ab5ef518f585d4850b0c7e95a4025ef5f95c4e137108e39cd4b1927c"
},
"downloads": -1,
"filename": "entity_linker_client-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "517900181f2cbfef728ead81e972d1fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12861,
"upload_time": "2025-08-19T01:52:31",
"upload_time_iso_8601": "2025-08-19T01:52:31.279801Z",
"url": "https://files.pythonhosted.org/packages/56/da/b000cafac4bd4a06ecac31047609686ce9c67c122a2cf9d10514abc00afa/entity_linker_client-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ebfef3ff56e93dc4b2d780682ecf8c1cb9a05ec092bdc49ceba893ff0e270aab",
"md5": "56bf775a50cf540b9b0614ed864f51e9",
"sha256": "dce009f06cc65bb4c4f75c0bd388e5a11b6a6b17b41bcaf699bf0d38898e8a32"
},
"downloads": -1,
"filename": "entity_linker_client-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "56bf775a50cf540b9b0614ed864f51e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15093,
"upload_time": "2025-08-19T01:52:33",
"upload_time_iso_8601": "2025-08-19T01:52:33.235007Z",
"url": "https://files.pythonhosted.org/packages/eb/fe/f3ff56e93dc4b2d780682ecf8c1cb9a05ec092bdc49ceba893ff0e270aab/entity_linker_client-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 01:52:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "godel-ai",
"github_project": "entity-linker-client",
"github_not_found": true,
"lcname": "entity-linker-client"
}
JSON
