# Ragger Python SDK
Python SDK for the Ragger RAG (Retrieval Augmented Generation) API. Build powerful AI applications that can search and answer questions using your own documents.
## Features
- **Easy Integration**: Simple Python client. With a few lines of code, you can build a complete RAG application.
- **Document Upload**: Support for PDF, Word, text, markdown, and other formats
- **Vector Indexing**: Create searchable embeddings from your documents
- **Natural Language Queries**: Ask questions and get AI-powered answers with advanced reasoning
- **Conversation Memory**: Maintain context across multiple queries
- **Multi-tenant**: Organization and project-based document isolation
- **Async Processing**: Handle large documents with background processing
## Installation
```bash
pip install ragger-python-sdk
```
## Quick Start
1. Initialize the client
```python
from ragger_sdk import RaggerClient
client = RaggerClient(
base_url="https://your-ragger-server.com/rag/api/v1",
token="your-api-token"
)
```
2. Upload a document
```python
upload_result = client.documents.upload(
organization="my-company",
project="knowledge-base",
name="user-manual",
file_path="/path/to/manual.pdf"
)
```
3. Create searchable index
```python
index_result = client.index.index(
organization="my-company",
project="knowledge-base"
)
task_id = index_result['task_id']
# Wait for indexing to complete
status = client.index.status(task_id, organization="my-company")
```
4. Ask questions
```python
answer = client.query.ask(
query="How do I reset my password?",
organization="my-company",
project="knowledge-base",
user="support@company.com"
)
print(f"Answer: {answer['answer']}")
# Assistant: "To reset your password, go to the login page and click 'Forgot Password'..."
print(f"Source: {answer['metadata']['sources']}")
# "Source: {'https://intranet.company.com/policy', 'https://help.company.com/reset-password'}"
print(f"Session ID: {answer['session_id']}")
# 123456789abcdef
```
5. Maintain conversation context
```python
followup_answer = client.query.ask(
query="Sorry, I meant username recovery",
organization="my-company",
project="knowledge-base",
user="support@company.com",
session_id="123456789abcdef"
)
# Answer: "Unlike password resets, username recovery usually requires contacting support..."
```
## Core Concepts
- **Organization**: Top-level container for your projects
- **Project**: Collection of related documents and their index
- **Document**: Individual files (PDF, Word, text, etc.) containing your data
- **Index**: Searchable vector representation of your documents
- **Query**: Natural language questions answered using your documents
## API Reference
### Client Initialization
```python
client = RaggerClient(
base_url="https://api.ragger.ai/v1", # Your Ragger server URL
token="your-api-token", # API authentication token
timeout=30, # Request timeout in seconds
verify_ssl=True # SSL certificate verification
)
```
### Document Management
```python
# Upload from file
response = client.documents.upload(
organization="org-name",
project="project-name",
name="document-name",
file_path="/path/to/file.pdf",
metadata={"author": "John Doe", "department": "Engineering"},
system_prompt="You are a helpful assistant for company policies",
text_search_config="english"
)
# Upload from text content
response = client.documents.upload(
organization="org-name",
project="project-name",
name="document-name",
content="Your text content here...",
content_type="text/markdown",
metadata={"source": "manual_entry"}
)
# Check processing status
status = client.documents.status(
task_id=response['task_id'],
organization="org-name"
)
```
### Index Management
```python
# Create/update index
response = client.index.index(
organization="org-name",
project="project-name",
force_overwrite=False
)
# Check indexing status
task_id = response['task_id']
status = client.index.status(
task_id=task_id,
organization="org-name"
)
```
### Querying
```python
# Basic query
answer = client.query.ask(
query="What is the return policy?",
organization="org-name",
project="project-name",
user="user@example.com"
)
# Query with session (maintains conversation context)
answer = client.query.ask(
query="Tell me more about that",
organization="org-name",
project="project-name",
user="user@example.com",
session_id="conversation-123"
)
```
### Deleting Documents
```python
# Delete a single document by name
response = client.documents.delete(
organization="org-name",
project="project-name",
name="document-name"
)
# Delete all documents in a project (use with caution!)
response = client.documents.delete(
organization="org-name",
project="project-name",
delete_all=True
)
```
### Chat History
```python
# Get all sessions for a user
sessions = client.chat_history.sessions(
organization="org-name",
project="project-name",
user="user@example.com"
)
# Get specific session details
session = client.chat_history.session(
organization="org-name",
project="project-name",
user="user@example.com",
session_id="session-123"
)
```
### Error Handling
The SDK raises `RaggerAPIError` for API-related issues. You can inspect the error type:
```python
try:
result = client.some_operation()
except RaggerAPIError as e:
if e.is_validation_error():
# Handle parameter validation
elif e.is_not_found():
# Handle missing resources
elif e.is_conflict():
# Handle resource conflicts
```
## Examples
See the `examples/` directory for complete usage examples:
- `documents_from_file_example.py` - File upload and processing
- `index_example.py` - Vector index creation
- `query_example.py` - Natural language querying
- `chat_history_example.py` - Conversation management
## Requirements
- Python 3.8+
- requests >= 2.25.0
## License
MIT License - see LICENSE file for details.
## Support
- Documentation: [GitHub README](https://github.com/RaggerAI/python-sdk/#readme)
- Issues: [GitHub Issues](https://github.com/RaggerAI/python-sdk//issues)
- Source: [GitHub Repository](https://github.com/RaggerAI/python-sdk/)
## Development
To contribute or modify the SDK, clone the repository and install dependencies:
```bash
git clone <repository-url>
cd ragger-sdk
# Create a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate # On Windows use `venv\Scripts\activate`
pip install -r requirements.txt
```
Create a tagged release:
```bash
git tag -a vX.Y.Z -m "Release version X.Y.Z"
git push origin vX.Y.Z
```
Raw data
{
"_id": null,
"home_page": "https://github.com/RaggerAI/python-sdk",
"name": "ragger-python-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "rag, retrieval, augmented, generation, ai, llm, nlp, vector, search, embeddings, semantic-search, document-processing",
"author": "Ragger Team",
"author_email": "support@ragger.ai",
"download_url": "https://files.pythonhosted.org/packages/0d/04/96af27b3768bbcdc1c9c98e0e9d9a0c639d8d16cb31eea97f2a9a503e08c/ragger_python_sdk-0.1.3.tar.gz",
"platform": null,
"description": "# Ragger Python SDK\n\nPython SDK for the Ragger RAG (Retrieval Augmented Generation) API. Build powerful AI applications that can search and answer questions using your own documents.\n\n## Features\n\n- **Easy Integration**: Simple Python client. With a few lines of code, you can build a complete RAG application.\n- **Document Upload**: Support for PDF, Word, text, markdown, and other formats\n- **Vector Indexing**: Create searchable embeddings from your documents\n- **Natural Language Queries**: Ask questions and get AI-powered answers with advanced reasoning\n- **Conversation Memory**: Maintain context across multiple queries\n- **Multi-tenant**: Organization and project-based document isolation\n- **Async Processing**: Handle large documents with background processing\n\n## Installation\n\n```bash\npip install ragger-python-sdk\n```\n\n## Quick Start\n\n1. Initialize the client\n\n```python\nfrom ragger_sdk import RaggerClient\nclient = RaggerClient(\n base_url=\"https://your-ragger-server.com/rag/api/v1\",\n token=\"your-api-token\"\n)\n```\n\n2. Upload a document\n\n```python\nupload_result = client.documents.upload(\n organization=\"my-company\",\n project=\"knowledge-base\",\n name=\"user-manual\",\n file_path=\"/path/to/manual.pdf\"\n)\n```\n\n3. Create searchable index\n\n```python\nindex_result = client.index.index(\n organization=\"my-company\",\n project=\"knowledge-base\"\n)\ntask_id = index_result['task_id']\n\n# Wait for indexing to complete\nstatus = client.index.status(task_id, organization=\"my-company\")\n```\n\n4. Ask questions\n\n```python\nanswer = client.query.ask(\n query=\"How do I reset my password?\",\n organization=\"my-company\",\n project=\"knowledge-base\",\n user=\"support@company.com\"\n)\n\nprint(f\"Answer: {answer['answer']}\")\n# Assistant: \"To reset your password, go to the login page and click 'Forgot Password'...\"\n\nprint(f\"Source: {answer['metadata']['sources']}\")\n# \"Source: {'https://intranet.company.com/policy', 'https://help.company.com/reset-password'}\"\n\nprint(f\"Session ID: {answer['session_id']}\")\n# 123456789abcdef\n```\n\n5. Maintain conversation context\n\n```python\nfollowup_answer = client.query.ask(\n query=\"Sorry, I meant username recovery\",\n organization=\"my-company\",\n project=\"knowledge-base\",\n user=\"support@company.com\",\n session_id=\"123456789abcdef\"\n)\n# Answer: \"Unlike password resets, username recovery usually requires contacting support...\"\n```\n\n## Core Concepts\n\n- **Organization**: Top-level container for your projects\n- **Project**: Collection of related documents and their index\n- **Document**: Individual files (PDF, Word, text, etc.) containing your data\n- **Index**: Searchable vector representation of your documents\n- **Query**: Natural language questions answered using your documents\n\n## API Reference\n\n### Client Initialization\n\n```python\nclient = RaggerClient(\n base_url=\"https://api.ragger.ai/v1\", # Your Ragger server URL\n token=\"your-api-token\", # API authentication token\n timeout=30, # Request timeout in seconds\n verify_ssl=True # SSL certificate verification\n)\n```\n\n### Document Management\n\n```python\n# Upload from file\nresponse = client.documents.upload(\n organization=\"org-name\",\n project=\"project-name\",\n name=\"document-name\",\n file_path=\"/path/to/file.pdf\",\n metadata={\"author\": \"John Doe\", \"department\": \"Engineering\"},\n system_prompt=\"You are a helpful assistant for company policies\",\n text_search_config=\"english\"\n)\n\n# Upload from text content\nresponse = client.documents.upload(\n organization=\"org-name\",\n project=\"project-name\",\n name=\"document-name\",\n content=\"Your text content here...\",\n content_type=\"text/markdown\",\n metadata={\"source\": \"manual_entry\"}\n)\n\n# Check processing status\nstatus = client.documents.status(\n task_id=response['task_id'],\n organization=\"org-name\"\n)\n```\n\n### Index Management\n\n```python\n# Create/update index\nresponse = client.index.index(\n organization=\"org-name\",\n project=\"project-name\",\n force_overwrite=False\n)\n\n# Check indexing status\ntask_id = response['task_id']\nstatus = client.index.status(\n task_id=task_id,\n organization=\"org-name\"\n)\n```\n\n### Querying\n\n```python\n# Basic query\nanswer = client.query.ask(\n query=\"What is the return policy?\",\n organization=\"org-name\",\n project=\"project-name\",\n user=\"user@example.com\"\n)\n\n# Query with session (maintains conversation context)\nanswer = client.query.ask(\n query=\"Tell me more about that\",\n organization=\"org-name\",\n project=\"project-name\",\n user=\"user@example.com\",\n session_id=\"conversation-123\"\n)\n```\n\n### Deleting Documents\n\n```python\n# Delete a single document by name\nresponse = client.documents.delete(\n organization=\"org-name\",\n project=\"project-name\",\n name=\"document-name\"\n)\n\n# Delete all documents in a project (use with caution!)\nresponse = client.documents.delete(\n organization=\"org-name\",\n project=\"project-name\",\n delete_all=True\n)\n```\n\n### Chat History\n\n```python\n# Get all sessions for a user\nsessions = client.chat_history.sessions(\n organization=\"org-name\",\n project=\"project-name\",\n user=\"user@example.com\"\n)\n\n# Get specific session details\nsession = client.chat_history.session(\n organization=\"org-name\",\n project=\"project-name\",\n user=\"user@example.com\",\n session_id=\"session-123\"\n)\n```\n\n### Error Handling\n\nThe SDK raises `RaggerAPIError` for API-related issues. You can inspect the error type:\n\n```python\ntry:\n result = client.some_operation()\nexcept RaggerAPIError as e:\n if e.is_validation_error():\n # Handle parameter validation\n elif e.is_not_found():\n # Handle missing resources\n elif e.is_conflict():\n # Handle resource conflicts\n```\n\n## Examples\n\nSee the `examples/` directory for complete usage examples:\n\n- `documents_from_file_example.py` - File upload and processing\n- `index_example.py` - Vector index creation\n- `query_example.py` - Natural language querying\n- `chat_history_example.py` - Conversation management\n\n## Requirements\n\n- Python 3.8+\n- requests >= 2.25.0\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\n- Documentation: [GitHub README](https://github.com/RaggerAI/python-sdk/#readme)\n- Issues: [GitHub Issues](https://github.com/RaggerAI/python-sdk//issues)\n- Source: [GitHub Repository](https://github.com/RaggerAI/python-sdk/)\n\n## Development\n\nTo contribute or modify the SDK, clone the repository and install dependencies:\n\n```bash\ngit clone <repository-url>\ncd ragger-sdk\n# Create a virtual environment (optional but recommended)\npython -m venv venv\nsource venv/bin/activate # On Windows use `venv\\Scripts\\activate`\npip install -r requirements.txt\n```\n\nCreate a tagged release:\n\n```bash\ngit tag -a vX.Y.Z -m \"Release version X.Y.Z\"\ngit push origin vX.Y.Z\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for ragger.ai RAG API",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://github.com/RaggerAI/python-sdk#readme",
"Homepage": "https://github.com/RaggerAI/python-sdk",
"Repository": "https://github.com/RaggerAI/python-sdk"
},
"split_keywords": [
"rag",
" retrieval",
" augmented",
" generation",
" ai",
" llm",
" nlp",
" vector",
" search",
" embeddings",
" semantic-search",
" document-processing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "216e5b8a06a568e83692d78cfb811422a7404d4034bfabffb5f04907924bf8f4",
"md5": "6c2583052c4dfcb74a8bf13dc3c2af2e",
"sha256": "fa2d41562140a20e2711f7c165dcc31155f63f8fa4239b1247a643e9e021fd7d"
},
"downloads": -1,
"filename": "ragger_python_sdk-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c2583052c4dfcb74a8bf13dc3c2af2e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 18823,
"upload_time": "2025-10-09T20:47:02",
"upload_time_iso_8601": "2025-10-09T20:47:02.071325Z",
"url": "https://files.pythonhosted.org/packages/21/6e/5b8a06a568e83692d78cfb811422a7404d4034bfabffb5f04907924bf8f4/ragger_python_sdk-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0d0496af27b3768bbcdc1c9c98e0e9d9a0c639d8d16cb31eea97f2a9a503e08c",
"md5": "065bd761cc1fbc5c8594cf21a34b6198",
"sha256": "f524fa600d7659fa5af92bcf377c416bbcc5fa63c6c914b98d6bd842c304097f"
},
"downloads": -1,
"filename": "ragger_python_sdk-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "065bd761cc1fbc5c8594cf21a34b6198",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 18543,
"upload_time": "2025-10-09T20:47:03",
"upload_time_iso_8601": "2025-10-09T20:47:03.448076Z",
"url": "https://files.pythonhosted.org/packages/0d/04/96af27b3768bbcdc1c9c98e0e9d9a0c639d8d16cb31eea97f2a9a503e08c/ragger_python_sdk-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-09 20:47:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RaggerAI",
"github_project": "python-sdk",
"github_not_found": true,
"lcname": "ragger-python-sdk"
}
JSON
