proofpudding 0.1.0__tar.gz

proofpudding-0.1.0/.gitignore

@@ -0,0 +1,140 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

proofpudding-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pudding AI
+
+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.

proofpudding-0.1.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: proofpudding
+Version: 0.1.0
+Summary: Python SDK for the Pudding API - Document processing and Q&A
+Project-URL: Homepage, https://github.com/pudding-ai/pudding-sdk
+Project-URL: Documentation, https://github.com/pudding-ai/pudding-sdk#readme
+Project-URL: Repository, https://github.com/pudding-ai/pudding-sdk
+Project-URL: Issues, https://github.com/pudding-ai/pudding-sdk/issues
+Author-email: Pudding Team <support@pudding.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,document-processing,pdf,pudding,question-answering,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Pudding SDK
+
+A Python SDK for the Pudding API - Document processing and question answering.
+
+[![PyPI version](https://badge.fury.io/py/pudding-sdk.svg)](https://badge.fury.io/py/pudding-sdk)
+[![Python Versions](https://img.shields.io/pypi/pyversions/pudding-sdk.svg)](https://pypi.org/project/pudding-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install pudding-sdk
+```
+
+## Requirements
+
+- Python 3.10+
+- httpx
+- pydantic >= 2.0
+
+## Quick Start
+
+```python
+from pudding import PuddingClient
+from pudding.exceptions import NotFoundError, ValidationError
+
+# Initialize client
+client = PuddingClient(access_token="pk_your_api_key")
+
+# Check API health
+health = client.health.check()
+print(f"API Status: {health.status}")
+
+# Upload a document
+doc = client.documents.upload(file_path="./contract.pdf")
+print(f"Uploaded: {doc.id}")
+
+# Ask a question about the document
+job = client.jobs.create(
+    document_id=doc.id,
+    question="What is the effective date of this contract?"
+)
+
+if job.success:
+    print(f"Answer: {job.result.answer}")
+    print(f"Confidence: {job.result.confidence}")
+    for citation in job.result.citations:
+        print(f"  - Page {citation.page}: {citation.quote}")
+else:
+    print(f"Failed: {job.error}")
+
+# List all documents with pagination
+docs = client.documents.list(skip=0, limit=10)
+print(f"Total documents: {docs.total}")
+for doc in docs.items:
+    print(f"  - {doc.filename} ({doc.size_bytes} bytes)")
+
+# List jobs for a specific document
+jobs = client.jobs.list(document_id=doc.id)
+
+# Delete a document (also deletes associated jobs)
+try:
+    deleted = client.documents.delete(document_id=doc.id)
+    print(f"Deleted: {deleted.filename}")
+except NotFoundError:
+    print("Document not found")
+```
+
+## Async Support
+
+The SDK provides both synchronous and asynchronous clients:
+
+```python
+from pudding import PuddingClient, AsyncPuddingClient
+
+# Synchronous client
+client = PuddingClient(access_token="pk_your_api_key")
+docs = client.documents.list()
+
+# Asynchronous client
+async_client = AsyncPuddingClient(access_token="pk_your_api_key")
+docs = await async_client.documents.list()
+```
+
+## Context Manager Support
+
+Both clients support context managers for proper resource cleanup:
+
+```python
+# Synchronous
+with PuddingClient(access_token="pk_your_api_key") as client:
+    docs = client.documents.list()
+
+# Asynchronous
+async with AsyncPuddingClient(access_token="pk_your_api_key") as client:
+    docs = await client.documents.list()
+```
+
+## Configuration
+
+### Initialization Options
+
+```python
+client = PuddingClient(
+    access_token="pk_your_api_key",  # Required: Your API key
+    timeout=60.0,                     # Optional: Request timeout in seconds (default: 1800 for jobs)
+    max_retries=3,                    # Optional: Max retries for transient errors (default: 3)
+)
+```
+
+### Custom Timeout for Jobs
+
+Job creation is a blocking operation that waits for document processing. The default timeout is 1800 seconds (30 minutes):
+
+```python
+# Use a custom timeout for the entire client
+client = PuddingClient(access_token="...", timeout=3600.0)  # 1 hour
+```
+
+## API Reference
+
+### Health Checks
+
+```python
+# Check API health
+health = client.health.check()
+print(health.status)      # "healthy"
+print(health.version)     # API version
+print(health.environment) # Environment name
+
+# Check readiness (includes database status)
+ready = client.health.ready()
+print(ready.status)    # "ready" or "not_ready"
+print(ready.database)  # "connected" or error message
+```
+
+### Documents
+
+```python
+# Upload a document from file path
+doc = client.documents.upload(file_path="/path/to/document.pdf")
+
+# Upload a document from bytes
+with open("document.pdf", "rb") as f:
+    doc = client.documents.upload(file=f.read(), filename="document.pdf")
+
+# List documents with pagination
+doc_list = client.documents.list(skip=0, limit=20)
+print(f"Total: {doc_list.total}")
+for doc in doc_list.items:
+    print(f"{doc.id}: {doc.filename}")
+
+# Delete a document
+deleted_doc = client.documents.delete(document_id="uuid-string")
+```
+
+### Jobs
+
+```python
+# Create a job (process document with a question)
+job = client.jobs.create(
+    document_id="uuid-string",
+    question="What is the total revenue mentioned in this document?"
+)
+
+# Access job results
+if job.success:
+    print(job.result.answer)
+    print(job.result.confidence)  # "high", "medium", "low", or "not_found"
+    for citation in job.result.citations:
+        print(f"Page {citation.page}: {citation.quote}")
+
+# List all jobs
+job_list = client.jobs.list(skip=0, limit=20)
+
+# List jobs for a specific document
+job_list = client.jobs.list(document_id="uuid-string")
+```
+
+## Exception Handling
+
+The SDK provides a comprehensive exception hierarchy:
+
+```python
+from pudding.exceptions import (
+    PuddingError,        # Base exception for all SDK errors
+    AuthenticationError, # 401: Invalid or missing API key
+    NotFoundError,       # 404: Resource not found
+    ValidationError,     # 400: Invalid request
+    RateLimitError,      # 429: Too many requests
+    ServerError,         # 500: Internal server error
+    GatewayError,        # 502: Upstream service error
+    TimeoutError,        # 504: Request timed out
+)
+
+try:
+    doc = client.documents.upload(file_path="./document.txt")
+except ValidationError as e:
+    print(f"Validation failed: {e.message}")  # "Only PDF files are allowed"
+except AuthenticationError as e:
+    print(f"Auth failed: {e.message}")
+except PuddingError as e:
+    print(f"API error ({e.status_code}): {e.message}")
+```
+
+## Logging
+
+The SDK uses Python's standard logging module. Configure logging level as needed:
+
+```python
+import logging
+
+# Enable debug logging for the SDK
+logging.getLogger("pudding").setLevel(logging.DEBUG)
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/pudding-ai/pudding-sdk.git
+cd pudding-sdk
+
+# Install with development dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Running Tests with Coverage
+
+```bash
+pytest --cov=pudding --cov-report=html
+```
+
+### Type Checking
+
+```bash
+mypy src/pudding
+```
+
+### Linting
+
+```bash
+ruff check src/pudding tests
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

proofpudding-0.1.0/README.md

@@ -0,0 +1,256 @@
+# Pudding SDK
+
+A Python SDK for the Pudding API - Document processing and question answering.
+
+[![PyPI version](https://badge.fury.io/py/pudding-sdk.svg)](https://badge.fury.io/py/pudding-sdk)
+[![Python Versions](https://img.shields.io/pypi/pyversions/pudding-sdk.svg)](https://pypi.org/project/pudding-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install pudding-sdk
+```
+
+## Requirements
+
+- Python 3.10+
+- httpx
+- pydantic >= 2.0
+
+## Quick Start
+
+```python
+from pudding import PuddingClient
+from pudding.exceptions import NotFoundError, ValidationError
+
+# Initialize client
+client = PuddingClient(access_token="pk_your_api_key")
+
+# Check API health
+health = client.health.check()
+print(f"API Status: {health.status}")
+
+# Upload a document
+doc = client.documents.upload(file_path="./contract.pdf")
+print(f"Uploaded: {doc.id}")
+
+# Ask a question about the document
+job = client.jobs.create(
+    document_id=doc.id,
+    question="What is the effective date of this contract?"
+)
+
+if job.success:
+    print(f"Answer: {job.result.answer}")
+    print(f"Confidence: {job.result.confidence}")
+    for citation in job.result.citations:
+        print(f"  - Page {citation.page}: {citation.quote}")
+else:
+    print(f"Failed: {job.error}")
+
+# List all documents with pagination
+docs = client.documents.list(skip=0, limit=10)
+print(f"Total documents: {docs.total}")
+for doc in docs.items:
+    print(f"  - {doc.filename} ({doc.size_bytes} bytes)")
+
+# List jobs for a specific document
+jobs = client.jobs.list(document_id=doc.id)
+
+# Delete a document (also deletes associated jobs)
+try:
+    deleted = client.documents.delete(document_id=doc.id)
+    print(f"Deleted: {deleted.filename}")
+except NotFoundError:
+    print("Document not found")
+```
+
+## Async Support
+
+The SDK provides both synchronous and asynchronous clients:
+
+```python
+from pudding import PuddingClient, AsyncPuddingClient
+
+# Synchronous client
+client = PuddingClient(access_token="pk_your_api_key")
+docs = client.documents.list()
+
+# Asynchronous client
+async_client = AsyncPuddingClient(access_token="pk_your_api_key")
+docs = await async_client.documents.list()
+```
+
+## Context Manager Support
+
+Both clients support context managers for proper resource cleanup:
+
+```python
+# Synchronous
+with PuddingClient(access_token="pk_your_api_key") as client:
+    docs = client.documents.list()
+
+# Asynchronous
+async with AsyncPuddingClient(access_token="pk_your_api_key") as client:
+    docs = await client.documents.list()
+```
+
+## Configuration
+
+### Initialization Options
+
+```python
+client = PuddingClient(
+    access_token="pk_your_api_key",  # Required: Your API key
+    timeout=60.0,                     # Optional: Request timeout in seconds (default: 1800 for jobs)
+    max_retries=3,                    # Optional: Max retries for transient errors (default: 3)
+)
+```
+
+### Custom Timeout for Jobs
+
+Job creation is a blocking operation that waits for document processing. The default timeout is 1800 seconds (30 minutes):
+
+```python
+# Use a custom timeout for the entire client
+client = PuddingClient(access_token="...", timeout=3600.0)  # 1 hour
+```
+
+## API Reference
+
+### Health Checks
+
+```python
+# Check API health
+health = client.health.check()
+print(health.status)      # "healthy"
+print(health.version)     # API version
+print(health.environment) # Environment name
+
+# Check readiness (includes database status)
+ready = client.health.ready()
+print(ready.status)    # "ready" or "not_ready"
+print(ready.database)  # "connected" or error message
+```
+
+### Documents
+
+```python
+# Upload a document from file path
+doc = client.documents.upload(file_path="/path/to/document.pdf")
+
+# Upload a document from bytes
+with open("document.pdf", "rb") as f:
+    doc = client.documents.upload(file=f.read(), filename="document.pdf")
+
+# List documents with pagination
+doc_list = client.documents.list(skip=0, limit=20)
+print(f"Total: {doc_list.total}")
+for doc in doc_list.items:
+    print(f"{doc.id}: {doc.filename}")
+
+# Delete a document
+deleted_doc = client.documents.delete(document_id="uuid-string")
+```
+
+### Jobs
+
+```python
+# Create a job (process document with a question)
+job = client.jobs.create(
+    document_id="uuid-string",
+    question="What is the total revenue mentioned in this document?"
+)
+
+# Access job results
+if job.success:
+    print(job.result.answer)
+    print(job.result.confidence)  # "high", "medium", "low", or "not_found"
+    for citation in job.result.citations:
+        print(f"Page {citation.page}: {citation.quote}")
+
+# List all jobs
+job_list = client.jobs.list(skip=0, limit=20)
+
+# List jobs for a specific document
+job_list = client.jobs.list(document_id="uuid-string")
+```
+
+## Exception Handling
+
+The SDK provides a comprehensive exception hierarchy:
+
+```python
+from pudding.exceptions import (
+    PuddingError,        # Base exception for all SDK errors
+    AuthenticationError, # 401: Invalid or missing API key
+    NotFoundError,       # 404: Resource not found
+    ValidationError,     # 400: Invalid request
+    RateLimitError,      # 429: Too many requests
+    ServerError,         # 500: Internal server error
+    GatewayError,        # 502: Upstream service error
+    TimeoutError,        # 504: Request timed out
+)
+
+try:
+    doc = client.documents.upload(file_path="./document.txt")
+except ValidationError as e:
+    print(f"Validation failed: {e.message}")  # "Only PDF files are allowed"
+except AuthenticationError as e:
+    print(f"Auth failed: {e.message}")
+except PuddingError as e:
+    print(f"API error ({e.status_code}): {e.message}")
+```
+
+## Logging
+
+The SDK uses Python's standard logging module. Configure logging level as needed:
+
+```python
+import logging
+
+# Enable debug logging for the SDK
+logging.getLogger("pudding").setLevel(logging.DEBUG)
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/pudding-ai/pudding-sdk.git
+cd pudding-sdk
+
+# Install with development dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Running Tests with Coverage
+
+```bash
+pytest --cov=pudding --cov-report=html
+```
+
+### Type Checking
+
+```bash
+mypy src/pudding
+```
+
+### Linting
+
+```bash
+ruff check src/pudding tests
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.