documentors 0.1.0__tar.gz

documentors-0.1.0/.gitignore

@@ -0,0 +1,205 @@
+# Secrets and credentials (NEVER COMMIT)
+.env
+.env.*
+.env.secure.server
+.env.production
+*.key
+*.pem
+*_keys.txt
+vault-backup-CRITICAL.txt
+
+# Linode API tokens
+personal_access_token.txt
+*_access_token.txt
+*.token
+.linode-token
+
+# Terraform
+*.tfvars
+!*.tfvars.example
+*.tfstate
+*.tfstate.backup
+.terraform/
+.terraform.lock.hcl
+linode-verified-*.json
+
+# Python virtual environments
+.venv/
+venv/
+ENV/
+env/
+*.venv
+
+# Generated indexes and temp deploy artifacts
+.code_index.json
+.code_index_metadata.json
+tmp_deploy/
+
+# Python cache and compiled files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Python distribution / packaging
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+coverage.json
+.tox/
+htmlcov/
+.hypothesis/
+
+# Production database files
+*.db
+*.sqlite
+*.sqlite3
+
+# Logs
+*.log
+logs/
+ci-logs/
+
+# Docker volumes
+docker/data/
+**/data/
+*_data/
+*_backups/
+
+# Node.js (if present)
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Temporary files
+*.tmp
+*.temp
+tmp_*
+.DS_Store
+Thumbs.db
+
+# Build/test output artifacts
+build_output.txt
+test_output.txt
+test_result*.txt
+*_out.txt
+ssh_test.txt
+fairness_test_results.txt
+pip_outdated.json
+openapi_test.json
+test_register.json
+*_infrastructure_*.json
+*_infrastructure_*.md
+
+# Backup files
+*.backup
+*.old
+*.OLD
+*.bak
+
+# Binary archives (deployment artifacts)
+*.tar.gz
+*.tgz
+*.tar
+*.zip
+
+# Sensitive directories
+vault/
+
+# Runtime/temp folders
+watch_folders/
+errors/
+processed/
+
+# Deployment sensitive files
+deployment.config
+authorized_keys*
+*_key.txt
+*_keys.txt
+ssh_config_*
+
+# Binary executables
+*.exe
+*.dll
+
+# Auto-generated TypeScript
+next-env.d.ts
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Project status (machine-specific)
+project/status.yaml
+
+# Machine identity file (each machine has its own)
+.computer
+
+# Task folders (each machine only tracks its own)
+# On LEV: git update-index --skip-worktree project/tasks/asus project/tasks/gmk project/tasks/hp
+# On GMK: git update-index --skip-worktree project/tasks/asus project/tasks/lev project/tasks/hp
+project/tasks/*/
+
+# Large database migrations (>1MB)
+# These are stored on S:\ drive to avoid repo bloat
+# See migrations/sql/README.md for guidelines
+migrations/sql/*_bulk_*.sql
+migrations/sql/*_import_*.sql
+migrations/sql/*_performance_*.sql
+migrations/sql/V*__large_*.sql
+
+frontend/.next/
+frontend/tsconfig.tsbuildinfo
+hub/frontend/.next/
+hub/frontend/tsconfig.tsbuildinfo
+
+# Archival results — moved to S:\testing_results\
+DDL-Core/test-results/
+frontend/lighthouse-reports/
+
+# API Change Detection (machine-specific baselines)
+# Each developer may work with different backend versions
+frontend/.api-baseline.json
+frontend/.api-changes.log
+frontend/src/lib/api/generated-types.ts
+cookies.txt
+cookies2.txt
+proxy_cookies.txt
+
+# PDS publishing helper scripts (local utilities)
+migrations/_pds_demo_init.sql
+scripts/create_pds_page.ps1
+scripts/create_phishing_page.ps1
+scripts/create_phishing_page.py
+scripts/test_simple_page.ps1
+project/handoff/LEV_ONBOARDING.md
+
+# Next.js build artifacts
+hub/frontend/.next/
+frontend/.next/

documentors-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Docu-Mentors
+
+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.

documentors-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: documentors
+Version: 0.1.0
+Summary: Python SDK for the DocuMentors document lifecycle management platform
+Project-URL: Homepage, https://github.com/Docu-Mentors/developer-sdk
+Project-URL: Documentation, https://docs.docu-mentors.com/sdk/python
+Project-URL: Repository, https://github.com/Docu-Mentors/developer-sdk
+Project-URL: Issues, https://github.com/Docu-Mentors/developer-sdk/issues
+Author-email: Docu-Mentors <sdk@docu-mentors.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.25.0
+Requires-Dist: pydantic<3,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=7.0; extra == 'dev'
+Requires-Dist: respx<1,>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DocuMentors Python SDK
+
+Official Python SDK for the DocuMentors document lifecycle management API.
+
+## Installation
+
+```bash
+pip install documentors
+```
+
+Or install from source:
+
+```bash
+pip install -e sdk/python/
+```
+
+## Quick Start
+
+```python
+from documentors import DocumentorsClient
+
+client = DocumentorsClient(
+    base_url="https://your-instance.docu-mentors.com",
+    api_key="dk_prod_your_key_here",
+)
+
+# Upload a document
+doc = client.documents.upload("contract.pdf", title="Q2 Contract", classification="CONFIDENTIAL")
+
+# Scan for PII
+scan = client.security.detect_pii(doc.id)
+for finding in scan.findings:
+    print(f"{finding.type}: {finding.masked_value}")
+
+client.close()
+```
+
+## Authentication
+
+### API Key (recommended for integrations)
+
+```python
+client = DocumentorsClient(base_url="...", api_key="dk_prod_xxx")
+```
+
+### JWT (interactive / service-to-service)
+
+```python
+client = DocumentorsClient(base_url="...")
+client.login(email="user@example.com", password="secret")
+```
+
+### Context Manager
+
+```python
+with DocumentorsClient(base_url="...", api_key="dk_prod_xxx") as client:
+    docs = client.documents.list()
+```
+
+## Resource Namespaces
+
+| Namespace | Description |
+|---|---|
+| `client.documents` | Upload, list, get, delete, versions, download |
+| `client.security` | PII detection/redaction, phishing analysis |
+| `client.compliance` | Legal holds, eDiscovery, retention policies |
+| `client.admin` | Users, API keys, audit logs, devices |
+
+## Error Handling
+
+```python
+from documentors import DocumentorsClient, NotFoundError, RateLimitError
+
+try:
+    doc = client.documents.get("bad-id")
+except NotFoundError:
+    print("Document not found")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+```
+
+### Exception Hierarchy
+
+- `DocumentorsError` — base
+  - `AuthenticationError` — 401
+  - `PermissionDeniedError` — 403
+  - `NotFoundError` — 404
+  - `ValidationError` — 422
+  - `ConflictError` — 409
+  - `RateLimitError` — 429 (includes `retry_after`)
+  - `ServerError` — 500+
+
+## Transport Features
+
+- Automatic retry with exponential backoff on 429/5xx
+- `Retry-After` header support
+- Configurable timeout and max retries
+- Clean error mapping from HTTP status codes
+
+## Examples
+
+See [`examples/`](examples/) for full working scripts:
+
+- **quickstart.py** — Upload + PII scan + redaction
+- **bulk_upload.py** — Batch upload with auto-scan
+- **pii_scan_pipeline.py** — Full PII audit → CSV report
+- **compliance_report.py** — Legal holds + retention summary
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

documentors-0.1.0/README.md

@@ -0,0 +1,118 @@
+# DocuMentors Python SDK
+
+Official Python SDK for the DocuMentors document lifecycle management API.
+
+## Installation
+
+```bash
+pip install documentors
+```
+
+Or install from source:
+
+```bash
+pip install -e sdk/python/
+```
+
+## Quick Start
+
+```python
+from documentors import DocumentorsClient
+
+client = DocumentorsClient(
+    base_url="https://your-instance.docu-mentors.com",
+    api_key="dk_prod_your_key_here",
+)
+
+# Upload a document
+doc = client.documents.upload("contract.pdf", title="Q2 Contract", classification="CONFIDENTIAL")
+
+# Scan for PII
+scan = client.security.detect_pii(doc.id)
+for finding in scan.findings:
+    print(f"{finding.type}: {finding.masked_value}")
+
+client.close()
+```
+
+## Authentication
+
+### API Key (recommended for integrations)
+
+```python
+client = DocumentorsClient(base_url="...", api_key="dk_prod_xxx")
+```
+
+### JWT (interactive / service-to-service)
+
+```python
+client = DocumentorsClient(base_url="...")
+client.login(email="user@example.com", password="secret")
+```
+
+### Context Manager
+
+```python
+with DocumentorsClient(base_url="...", api_key="dk_prod_xxx") as client:
+    docs = client.documents.list()
+```
+
+## Resource Namespaces
+
+| Namespace | Description |
+|---|---|
+| `client.documents` | Upload, list, get, delete, versions, download |
+| `client.security` | PII detection/redaction, phishing analysis |
+| `client.compliance` | Legal holds, eDiscovery, retention policies |
+| `client.admin` | Users, API keys, audit logs, devices |
+
+## Error Handling
+
+```python
+from documentors import DocumentorsClient, NotFoundError, RateLimitError
+
+try:
+    doc = client.documents.get("bad-id")
+except NotFoundError:
+    print("Document not found")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+```
+
+### Exception Hierarchy
+
+- `DocumentorsError` — base
+  - `AuthenticationError` — 401
+  - `PermissionDeniedError` — 403
+  - `NotFoundError` — 404
+  - `ValidationError` — 422
+  - `ConflictError` — 409
+  - `RateLimitError` — 429 (includes `retry_after`)
+  - `ServerError` — 500+
+
+## Transport Features
+
+- Automatic retry with exponential backoff on 429/5xx
+- `Retry-After` header support
+- Configurable timeout and max retries
+- Clean error mapping from HTTP status codes
+
+## Examples
+
+See [`examples/`](examples/) for full working scripts:
+
+- **quickstart.py** — Upload + PII scan + redaction
+- **bulk_upload.py** — Batch upload with auto-scan
+- **pii_scan_pipeline.py** — Full PII audit → CSV report
+- **compliance_report.py** — Legal holds + retention summary
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

documentors-0.1.0/documentors/__init__.py

@@ -0,0 +1,59 @@
+"""DocuMentors Python SDK — secure document lifecycle management."""
+
+from .client import DocumentorsClient
+from .exceptions import (
+    AuthenticationError,
+    ConflictError,
+    DocumentorsError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    APIKey,
+    APIKeyCreated,
+    Document,
+    DocumentVersion,
+    LegalHold,
+    PaginatedResponse,
+    PhishingVerdict,
+    PIIFinding,
+    RetentionPolicy,
+    ScanHistoryEntry,
+    ScanResult,
+    TokenResponse,
+    URLThreat,
+    User,
+)
+
+__all__ = [
+    "DocumentorsClient",
+    # Exceptions
+    "DocumentorsError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "ConflictError",
+    # Models
+    "Document",
+    "DocumentVersion",
+    "PaginatedResponse",
+    "ScanResult",
+    "PIIFinding",
+    "ScanHistoryEntry",
+    "PhishingVerdict",
+    "URLThreat",
+    "LegalHold",
+    "RetentionPolicy",
+    "User",
+    "APIKey",
+    "APIKeyCreated",
+    "TokenResponse",
+]
+
+__version__ = "0.1.0"

documentors-0.1.0/documentors/_transport.py

@@ -0,0 +1,173 @@
+"""HTTP transport with retry, error mapping, and auth injection."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    ConflictError,
+    DocumentorsError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+logger = logging.getLogger("documentors")
+
+_STATUS_MAP: dict[int, type[DocumentorsError]] = {
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+}
+
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_MAX_RETRIES = 3
+_DEFAULT_BACKOFF_FACTOR = 0.5
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class Transport:
+    """Low-level HTTP helper used by resource modules."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        headers: dict[str, str],
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        backoff_factor: float = _DEFAULT_BACKOFF_FACTOR,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._headers = headers
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._backoff_factor = backoff_factor
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=self._headers,
+            timeout=self._timeout,
+            follow_redirects=True,
+        )
+
+    # -- public helpers -----------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+        data: Optional[dict[str, Any]] = None,
+        files: Optional[Any] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+    ) -> httpx.Response:
+        """Send an HTTP request with retry and error mapping."""
+        url = path if path.startswith("http") else path
+        headers = {**self._headers, **(extra_headers or {})}
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                resp = self._client.request(
+                    method,
+                    url,
+                    json=json,
+                    params=_strip_none(params),
+                    data=data,
+                    files=files,
+                    headers=headers,
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    self._sleep(attempt)
+                    continue
+                raise DocumentorsError(f"Connection error: {exc}") from exc
+
+            if resp.status_code < 400:
+                return resp
+
+            if resp.status_code in _RETRYABLE_STATUS and attempt < self._max_retries:
+                retry_after = _parse_retry_after(resp)
+                self._sleep(attempt, retry_after)
+                continue
+
+            self._raise_for_status(resp)
+
+        raise DocumentorsError(f"Request failed after {self._max_retries} retries") from last_exc
+
+    def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+    # -- internals ----------------------------------------------------------
+
+    def _sleep(self, attempt: int, override: Optional[float] = None) -> None:
+        delay = override if override is not None else self._backoff_factor * (2 ** (attempt - 1))
+        logger.debug("Retry attempt %d — sleeping %.1fs", attempt, delay)
+        time.sleep(delay)
+
+    @staticmethod
+    def _raise_for_status(resp: httpx.Response) -> None:
+        detail = ""
+        details: dict[str, Any] = {}
+        try:
+            body = resp.json()
+            detail = body.get("detail", body.get("message", ""))
+            details = body if isinstance(body, dict) else {}
+        except Exception:
+            detail = resp.text[:500]
+
+        if resp.status_code == 429:
+            raise RateLimitError(
+                detail or "Rate limit exceeded",
+                retry_after=_parse_retry_after(resp),
+                details=details,
+            )
+
+        exc_cls = _STATUS_MAP.get(resp.status_code, ServerError if resp.status_code >= 500 else DocumentorsError)
+        raise exc_cls(
+            detail or f"HTTP {resp.status_code}",
+            details=details,
+        )
+
+
+def _strip_none(params: Optional[dict[str, Any]]) -> Optional[dict[str, Any]]:
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _parse_retry_after(resp: httpx.Response) -> Optional[int]:
+    val = resp.headers.get("Retry-After")
+    if val is None:
+        return None
+    try:
+        return int(val)
+    except ValueError:
+        return None