| Name | owlib JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Python SDK for the Owlib AI Knowledge Platform |
| upload_time | 2025-08-24 22:14:02 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT License
Copyright (c) 2025 Owlib
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
ai
artificial-intelligence
knowledge-base
embedding
vector-search
nlp
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Owlib Python SDK
A Python client library for the [Owlib AI Knowledge Platform](https://owlib.ai) - making structured knowledge accessible to AI applications.
## Overview
Owlib is an AI-first knowledge platform that allows developers to create, share, and query structured knowledge bases optimized for AI applications. Similar to how Hugging Face hosts models and datasets, Owlib provides a platform for hosting and accessing AI-ready knowledge repositories.
This Python SDK provides a simple and intuitive interface to query knowledge bases and retrieve structured information for your AI applications.
## Features
- 🚀 **Simple API** - Clean, intuitive interface for querying knowledge bases
- 🔍 **Powerful Search** - Vector similarity search with metadata filtering
- 🛡️ **Robust Error Handling** - Comprehensive exception handling with meaningful error messages
- 🔑 **Flexible Authentication** - Support for API keys and environment variables
- 📦 **Rich Data Models** - Structured response objects with type hints
- ⚡ **Async Ready** - Built with modern Python practices
## Installation
Install the Owlib Python SDK using pip:
```bash
pip install owlib
```
## Quick Start
### 1. Get Your API Key
First, sign up for an account at [owlib.ai](https://owlib.ai) and obtain your API key from the dashboard.
### 2. Basic Usage
```python
from owlib import OwlibClient
# Initialize the client
client = OwlibClient(api_key="your-api-key-here")
# Or use environment variable OWLIB_API_KEY
# client = OwlibClient()
# Select a knowledge base
kb = client.knowledge_base("history/chinese_ancient")
# Query the knowledge base
results = kb.query("秦始皇统一六国", top_k=5)
# Process the results
for entry in results.entries:
print(f"Title: {entry.title}")
print(f"Similarity: {entry.similarity_score:.2f}")
print(f"Content: {entry.content[:200]}...")
print("---")
```
### 3. Fetch Specific Entries
```python
# Get a specific entry by ID
if results.entries:
entry_id = results.entries[0].id
full_entry = kb.fetch(entry_id)
print(f"Full content: {full_entry.content}")
```
## Authentication
### Using API Key Parameter
```python
from owlib import OwlibClient
client = OwlibClient(api_key="your-api-key")
```
### Using Environment Variable
Set the `OWLIB_API_KEY` environment variable:
```bash
export OWLIB_API_KEY="your-api-key"
```
Then initialize the client without parameters:
```python
from owlib import OwlibClient
client = OwlibClient() # Automatically reads from environment
```
### Using .env File
Create a `.env` file in your project root:
```
OWLIB_API_KEY=your-api-key-here
```
The SDK will automatically load environment variables from `.env` files.
## API Reference
### OwlibClient
The main client class for interacting with the Owlib platform.
#### Constructor
```python
OwlibClient(api_key=None, base_url="https://api.owlib.ai", timeout=30)
```
**Parameters:**
- `api_key` (str, optional): API key for authentication. If None, reads from `OWLIB_API_KEY` environment variable.
- `base_url` (str): Base URL for the API. Default: "https://api.owlib.ai"
- `timeout` (int): Request timeout in seconds. Default: 30
#### Methods
##### `knowledge_base(path: str) -> KnowledgeBase`
Get a KnowledgeBase instance for the specified path.
**Parameters:**
- `path` (str): Knowledge base path in format "namespace/name"
**Returns:**
- `KnowledgeBase`: Instance for querying and fetching entries
### KnowledgeBase
Represents a specific knowledge base and provides methods to query and fetch entries.
#### Methods
##### `query(query_text: str, top_k: int = 5) -> QueryResult`
Query the knowledge base for similar entries.
**Parameters:**
- `query_text` (str): The text to search for
- `top_k` (int): Maximum number of results to return (1-100, default: 5)
**Returns:**
- `QueryResult`: Object containing matching entries and metadata
##### `fetch(entry_id: str) -> Entry`
Fetch a specific entry by its ID.
**Parameters:**
- `entry_id` (str): Unique identifier of the entry
**Returns:**
- `Entry`: Complete entry object with all fields
### Data Models
#### Entry
Represents a knowledge entry from the knowledge base.
**Attributes:**
- `id` (str): Unique identifier
- `title` (str): Entry title
- `content` (str): Full text content
- `similarity_score` (float): Similarity score (0.0-1.0)
- `metadata` (dict): Additional metadata
#### QueryResult
Represents the result of a knowledge base query.
**Attributes:**
- `entries` (List[Entry]): List of matching entries
- `query_text` (str): Original query text
- `total_count` (int): Total number of results
**Methods:**
- `__len__()`: Returns number of entries
- `__iter__()`: Allows iteration over entries
- `__getitem__(index)`: Allows indexing into entries
## Error Handling
The SDK provides comprehensive error handling with specific exception types:
```python
from owlib import OwlibClient
from owlib.exceptions import (
AuthenticationError,
KnowledgeBaseNotFoundError,
EntryNotFoundError,
ValidationError,
APIError,
NetworkError,
TimeoutError
)
try:
client = OwlibClient(api_key="invalid-key")
kb = client.knowledge_base("history/chinese_ancient")
results = kb.query("test query")
except AuthenticationError:
print("Invalid API key")
except KnowledgeBaseNotFoundError:
print("Knowledge base not found")
except ValidationError as e:
print(f"Invalid input: {e}")
except NetworkError as e:
print(f"Network error: {e}")
except TimeoutError:
print("Request timed out")
except APIError as e:
print(f"API error: {e}")
```
## Advanced Usage
### Custom Configuration
```python
from owlib import OwlibClient
# Custom API endpoint and timeout
client = OwlibClient(
api_key="your-api-key",
base_url="https://your-custom-api.com",
timeout=60 # 60 seconds
)
```
### Working with Metadata
```python
kb = client.knowledge_base("tech/machine_learning")
results = kb.query("transformer architecture", top_k=3)
for entry in results.entries:
print(f"Title: {entry.title}")
print(f"Category: {entry.metadata.get('category', 'N/A')}")
print(f"Author: {entry.metadata.get('author', 'Unknown')}")
print("---")
```
### Batch Processing
```python
queries = [
"深度学习基础",
"神经网络架构",
"机器学习算法"
]
kb = client.knowledge_base("tech/ai_concepts")
for query in queries:
results = kb.query(query, top_k=3)
print(f"Query: {query}")
print(f"Found {len(results)} results")
for entry in results:
print(f" - {entry.title} (score: {entry.similarity_score:.2f})")
print()
```
## Requirements
- Python 3.7+
- requests >= 2.28.0
- python-dotenv >= 0.19.0
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Documentation**: [docs.owlib.ai](https://docs.owlib.ai)
- **Issues**: [GitHub Issues](https://github.com/owlib/owlib-python/issues)
- **Email**: support@owlib.ai
## Changelog
### v1.0.0
- Initial release
- Basic querying and fetching functionality
- Comprehensive error handling
- Environment variable support
- Full documentation and examples
Raw data
{
"_id": null,
"home_page": null,
"name": "owlib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Xiang Fei <xfey99@gmail.com>",
"keywords": "ai, artificial-intelligence, knowledge-base, embedding, vector-search, nlp",
"author": null,
"author_email": "Xiang Fei <xfey99@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/88/2c/4b3f9d19f54feeb6a6a8feea56b2d5fc807eb60a81494b9576206dbdc23a/owlib-0.1.0.tar.gz",
"platform": null,
"description": "# Owlib Python SDK\n\nA Python client library for the [Owlib AI Knowledge Platform](https://owlib.ai) - making structured knowledge accessible to AI applications.\n\n## Overview\n\nOwlib is an AI-first knowledge platform that allows developers to create, share, and query structured knowledge bases optimized for AI applications. Similar to how Hugging Face hosts models and datasets, Owlib provides a platform for hosting and accessing AI-ready knowledge repositories.\n\nThis Python SDK provides a simple and intuitive interface to query knowledge bases and retrieve structured information for your AI applications.\n\n## Features\n\n- \ud83d\ude80 **Simple API** - Clean, intuitive interface for querying knowledge bases\n- \ud83d\udd0d **Powerful Search** - Vector similarity search with metadata filtering\n- \ud83d\udee1\ufe0f **Robust Error Handling** - Comprehensive exception handling with meaningful error messages\n- \ud83d\udd11 **Flexible Authentication** - Support for API keys and environment variables\n- \ud83d\udce6 **Rich Data Models** - Structured response objects with type hints\n- \u26a1 **Async Ready** - Built with modern Python practices\n\n## Installation\n\nInstall the Owlib Python SDK using pip:\n\n```bash\npip install owlib\n```\n\n## Quick Start\n\n### 1. Get Your API Key\n\nFirst, sign up for an account at [owlib.ai](https://owlib.ai) and obtain your API key from the dashboard.\n\n### 2. Basic Usage\n\n```python\nfrom owlib import OwlibClient\n\n# Initialize the client\nclient = OwlibClient(api_key=\"your-api-key-here\")\n\n# Or use environment variable OWLIB_API_KEY\n# client = OwlibClient()\n\n# Select a knowledge base\nkb = client.knowledge_base(\"history/chinese_ancient\")\n\n# Query the knowledge base\nresults = kb.query(\"\u79e6\u59cb\u7687\u7edf\u4e00\u516d\u56fd\", top_k=5)\n\n# Process the results\nfor entry in results.entries:\n print(f\"Title: {entry.title}\")\n print(f\"Similarity: {entry.similarity_score:.2f}\")\n print(f\"Content: {entry.content[:200]}...\")\n print(\"---\")\n```\n\n### 3. Fetch Specific Entries\n\n```python\n# Get a specific entry by ID\nif results.entries:\n entry_id = results.entries[0].id\n full_entry = kb.fetch(entry_id)\n print(f\"Full content: {full_entry.content}\")\n```\n\n## Authentication\n\n### Using API Key Parameter\n\n```python\nfrom owlib import OwlibClient\n\nclient = OwlibClient(api_key=\"your-api-key\")\n```\n\n### Using Environment Variable\n\nSet the `OWLIB_API_KEY` environment variable:\n\n```bash\nexport OWLIB_API_KEY=\"your-api-key\"\n```\n\nThen initialize the client without parameters:\n\n```python\nfrom owlib import OwlibClient\n\nclient = OwlibClient() # Automatically reads from environment\n```\n\n### Using .env File\n\nCreate a `.env` file in your project root:\n\n```\nOWLIB_API_KEY=your-api-key-here\n```\n\nThe SDK will automatically load environment variables from `.env` files.\n\n## API Reference\n\n### OwlibClient\n\nThe main client class for interacting with the Owlib platform.\n\n#### Constructor\n\n```python\nOwlibClient(api_key=None, base_url=\"https://api.owlib.ai\", timeout=30)\n```\n\n**Parameters:**\n- `api_key` (str, optional): API key for authentication. If None, reads from `OWLIB_API_KEY` environment variable.\n- `base_url` (str): Base URL for the API. Default: \"https://api.owlib.ai\"\n- `timeout` (int): Request timeout in seconds. Default: 30\n\n#### Methods\n\n##### `knowledge_base(path: str) -> KnowledgeBase`\n\nGet a KnowledgeBase instance for the specified path.\n\n**Parameters:**\n- `path` (str): Knowledge base path in format \"namespace/name\"\n\n**Returns:**\n- `KnowledgeBase`: Instance for querying and fetching entries\n\n### KnowledgeBase\n\nRepresents a specific knowledge base and provides methods to query and fetch entries.\n\n#### Methods\n\n##### `query(query_text: str, top_k: int = 5) -> QueryResult`\n\nQuery the knowledge base for similar entries.\n\n**Parameters:**\n- `query_text` (str): The text to search for\n- `top_k` (int): Maximum number of results to return (1-100, default: 5)\n\n**Returns:**\n- `QueryResult`: Object containing matching entries and metadata\n\n##### `fetch(entry_id: str) -> Entry`\n\nFetch a specific entry by its ID.\n\n**Parameters:**\n- `entry_id` (str): Unique identifier of the entry\n\n**Returns:**\n- `Entry`: Complete entry object with all fields\n\n### Data Models\n\n#### Entry\n\nRepresents a knowledge entry from the knowledge base.\n\n**Attributes:**\n- `id` (str): Unique identifier\n- `title` (str): Entry title\n- `content` (str): Full text content\n- `similarity_score` (float): Similarity score (0.0-1.0)\n- `metadata` (dict): Additional metadata\n\n#### QueryResult\n\nRepresents the result of a knowledge base query.\n\n**Attributes:**\n- `entries` (List[Entry]): List of matching entries\n- `query_text` (str): Original query text\n- `total_count` (int): Total number of results\n\n**Methods:**\n- `__len__()`: Returns number of entries\n- `__iter__()`: Allows iteration over entries\n- `__getitem__(index)`: Allows indexing into entries\n\n## Error Handling\n\nThe SDK provides comprehensive error handling with specific exception types:\n\n```python\nfrom owlib import OwlibClient\nfrom owlib.exceptions import (\n AuthenticationError,\n KnowledgeBaseNotFoundError,\n EntryNotFoundError,\n ValidationError,\n APIError,\n NetworkError,\n TimeoutError\n)\n\ntry:\n client = OwlibClient(api_key=\"invalid-key\")\n kb = client.knowledge_base(\"history/chinese_ancient\")\n results = kb.query(\"test query\")\nexcept AuthenticationError:\n print(\"Invalid API key\")\nexcept KnowledgeBaseNotFoundError:\n print(\"Knowledge base not found\")\nexcept ValidationError as e:\n print(f\"Invalid input: {e}\")\nexcept NetworkError as e:\n print(f\"Network error: {e}\")\nexcept TimeoutError:\n print(\"Request timed out\")\nexcept APIError as e:\n print(f\"API error: {e}\")\n```\n\n## Advanced Usage\n\n### Custom Configuration\n\n```python\nfrom owlib import OwlibClient\n\n# Custom API endpoint and timeout\nclient = OwlibClient(\n api_key=\"your-api-key\",\n base_url=\"https://your-custom-api.com\",\n timeout=60 # 60 seconds\n)\n```\n\n### Working with Metadata\n\n```python\nkb = client.knowledge_base(\"tech/machine_learning\")\nresults = kb.query(\"transformer architecture\", top_k=3)\n\nfor entry in results.entries:\n print(f\"Title: {entry.title}\")\n print(f\"Category: {entry.metadata.get('category', 'N/A')}\")\n print(f\"Author: {entry.metadata.get('author', 'Unknown')}\")\n print(\"---\")\n```\n\n### Batch Processing\n\n```python\nqueries = [\n \"\u6df1\u5ea6\u5b66\u4e60\u57fa\u7840\",\n \"\u795e\u7ecf\u7f51\u7edc\u67b6\u6784\", \n \"\u673a\u5668\u5b66\u4e60\u7b97\u6cd5\"\n]\n\nkb = client.knowledge_base(\"tech/ai_concepts\")\n\nfor query in queries:\n results = kb.query(query, top_k=3)\n print(f\"Query: {query}\")\n print(f\"Found {len(results)} results\")\n for entry in results:\n print(f\" - {entry.title} (score: {entry.similarity_score:.2f})\")\n print()\n```\n\n## Requirements\n\n- Python 3.7+\n- requests >= 2.28.0\n- python-dotenv >= 0.19.0\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [docs.owlib.ai](https://docs.owlib.ai)\n- **Issues**: [GitHub Issues](https://github.com/owlib/owlib-python/issues)\n- **Email**: support@owlib.ai\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- Basic querying and fetching functionality\n- Comprehensive error handling\n- Environment variable support\n- Full documentation and examples\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Owlib\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Python SDK for the Owlib AI Knowledge Platform",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/owlib/owlib-python/issues",
"Changelog": "https://github.com/owlib/owlib-python/blob/main/CHANGELOG.md",
"Documentation": "https://docs.owlib.ai",
"Homepage": "https://owlib.ai",
"Repository": "https://github.com/owlib/owlib-python"
},
"split_keywords": [
"ai",
" artificial-intelligence",
" knowledge-base",
" embedding",
" vector-search",
" nlp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9fe33dad7cb80ed1bf169520768a1552fb11875cfdccee375b28cec88963270d",
"md5": "a266ccb4ac235581a36e58b4231fc66a",
"sha256": "e35d8167b019eabb8eece6079dd1a4c3f4df683c3bf0ce00085589de1a1578b7"
},
"downloads": -1,
"filename": "owlib-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a266ccb4ac235581a36e58b4231fc66a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12624,
"upload_time": "2025-08-24T22:14:01",
"upload_time_iso_8601": "2025-08-24T22:14:01.297803Z",
"url": "https://files.pythonhosted.org/packages/9f/e3/3dad7cb80ed1bf169520768a1552fb11875cfdccee375b28cec88963270d/owlib-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "882c4b3f9d19f54feeb6a6a8feea56b2d5fc807eb60a81494b9576206dbdc23a",
"md5": "abd6b74f8189e09669295efbb774e471",
"sha256": "448a4bc6fb0870c2fb4b2ffe4b3091fbdcc2113b34785ad804f484c9ac4b8026"
},
"downloads": -1,
"filename": "owlib-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "abd6b74f8189e09669295efbb774e471",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10977,
"upload_time": "2025-08-24T22:14:02",
"upload_time_iso_8601": "2025-08-24T22:14:02.922362Z",
"url": "https://files.pythonhosted.org/packages/88/2c/4b3f9d19f54feeb6a6a8feea56b2d5fc807eb60a81494b9576206dbdc23a/owlib-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 22:14:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "owlib",
"github_project": "owlib-python",
"github_not_found": true,
"lcname": "owlib"
}
