surfacedocs 0.1.0__tar.gz

surfacedocs-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+# 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/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# 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
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db

surfacedocs-0.1.0/AGENTS/CLIENT_TASK.md

@@ -0,0 +1,277 @@
+# Task: HTTP Client Implementation
+
+## Status: COMPLETE
+
+## Objective
+
+Implement the `SurfaceDocs` client class that saves documents to the ingress API.
+
+## Context
+
+- SETUP_TASK, SCHEMA_TASK, PROMPT_TASK complete
+- Client uses httpx for HTTP requests
+- Must call `POST /v1/documents` on ingress-api
+- Reference: `plans/python-sdk-spec.md`, `services/ingress-api/src/main.py`
+
+---
+
+## Deliverable
+
+Update `src/surfacedocs/client.py` with the complete `SurfaceDocs` class.
+
+---
+
+## API Endpoint
+
+```
+POST /v1/documents
+Host: ingress.surfacedocs.dev (prod) or ingress.dev.surfacedocs.dev (dev)
+Authorization: Bearer <api_key>
+Content-Type: application/json
+
+{
+  "title": "Document title",
+  "folder_id": "optional_folder_id",
+  "content_type": "markdown",
+  "metadata": {"source": "agent-name"},
+  "blocks": [...]
+}
+
+Response 201:
+{
+  "id": "doc_abc123",
+  "url": "https://app.surfacedocs.dev/d/doc_abc123",
+  "folder_id": "folder_xyz",
+  "title": "Document title",
+  "block_count": 5,
+  "created_at": "2024-01-01T00:00:00Z"
+}
+```
+
+---
+
+## Implementation
+
+```python
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from surfacedocs.exceptions import (
+    AuthenticationError,
+    FolderNotFoundError,
+    SurfaceDocsError,
+    ValidationError,
+)
+
+
+@dataclass
+class SaveResult:
+    """Result from saving a document."""
+    id: str
+    url: str
+    folder_id: str
+
+
+class SurfaceDocs:
+    """SurfaceDocs API client."""
+
+    PROD_URL = "https://ingress.surfacedocs.dev"
+    DEV_URL = "https://ingress.dev.surfacedocs.dev"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ):
+        """
+        Initialize the SurfaceDocs client.
+
+        Args:
+            api_key: API key (sd_live_xxx or sd_test_xxx).
+                     Falls back to SURFACEDOCS_API_KEY env var.
+            base_url: Override API URL. Auto-detected from key prefix if not set.
+        """
+        self.api_key = api_key or os.environ.get("SURFACEDOCS_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError("API key required. Pass api_key or set SURFACEDOCS_API_KEY.")
+
+        if base_url:
+            self.base_url = base_url.rstrip("/")
+        else:
+            self.base_url = self._detect_base_url(self.api_key)
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=30.0,
+        )
+
+    def _detect_base_url(self, api_key: str) -> str:
+        """Detect base URL from API key prefix."""
+        if api_key.startswith("sd_test_"):
+            return self.DEV_URL
+        return self.PROD_URL
+
+    def save(
+        self,
+        content: str | dict[str, Any],
+        folder_id: str | None = None,
+    ) -> SaveResult:
+        """
+        Save a document from LLM output.
+
+        Args:
+            content: JSON string or dict from LLM response
+            folder_id: Target folder (defaults to user's root folder)
+
+        Returns:
+            SaveResult with document ID and URL
+        """
+        # Parse content if string
+        if isinstance(content, str):
+            try:
+                data = json.loads(content)
+            except json.JSONDecodeError as e:
+                raise ValidationError(f"Invalid JSON: {e}")
+        else:
+            data = content
+
+        # Extract fields
+        title = data.get("title")
+        blocks = data.get("blocks")
+        metadata = data.get("metadata")
+
+        if not title:
+            raise ValidationError("Document must have a title")
+        if not blocks:
+            raise ValidationError("Document must have blocks")
+
+        return self.save_raw(
+            title=title,
+            blocks=blocks,
+            folder_id=folder_id,
+            metadata=metadata,
+        )
+
+    def save_raw(
+        self,
+        title: str,
+        blocks: list[dict[str, Any]],
+        folder_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> SaveResult:
+        """
+        Save a document with explicit parameters.
+
+        Args:
+            title: Document title
+            blocks: List of block dicts
+            folder_id: Target folder (defaults to user's root folder)
+            metadata: Optional metadata dict
+
+        Returns:
+            SaveResult with document ID and URL
+        """
+        payload: dict[str, Any] = {
+            "title": title,
+            "blocks": blocks,
+            "content_type": "markdown",
+        }
+
+        if folder_id:
+            payload["folder_id"] = folder_id
+        if metadata:
+            payload["metadata"] = metadata
+
+        response = self._client.post("/v1/documents", json=payload)
+        return self._handle_response(response)
+
+    def _handle_response(self, response: httpx.Response) -> SaveResult:
+        """Handle API response and map errors."""
+        if response.status_code == 201:
+            data = response.json()
+            return SaveResult(
+                id=data["id"],
+                url=data["url"],
+                folder_id=data["folder_id"],
+            )
+
+        # Error handling
+        try:
+            error_data = response.json()
+            detail = error_data.get("detail", str(error_data))
+        except Exception:
+            detail = response.text or f"HTTP {response.status_code}"
+
+        if response.status_code == 401:
+            raise AuthenticationError(f"Authentication failed: {detail}")
+        elif response.status_code == 403:
+            raise AuthenticationError(f"Access denied: {detail}")
+        elif response.status_code == 404:
+            raise FolderNotFoundError(f"Folder not found: {detail}")
+        elif response.status_code == 422:
+            raise ValidationError(f"Validation error: {detail}")
+        else:
+            raise SurfaceDocsError(f"API error ({response.status_code}): {detail}")
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> SurfaceDocs:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+```
+
+---
+
+## Verification
+
+```python
+from surfacedocs import SurfaceDocs, SurfaceDocsError
+
+# Should raise without API key
+try:
+    client = SurfaceDocs()
+except SurfaceDocsError:
+    print("Correctly raised error without API key")
+
+# Should detect dev URL
+import os
+os.environ["SURFACEDOCS_API_KEY"] = "sd_test_fake"
+client = SurfaceDocs()
+assert client.base_url == "https://ingress.dev.surfacedocs.dev"
+
+# Should detect prod URL
+client = SurfaceDocs(api_key="sd_live_fake")
+assert client.base_url == "https://ingress.surfacedocs.dev"
+
+# Context manager should work
+with SurfaceDocs(api_key="sd_test_fake") as client:
+    assert client.api_key == "sd_test_fake"
+```
+
+---
+
+## Definition of Done
+
+- [x] `SurfaceDocs` class implemented in `client.py`
+- [x] `SaveResult` dataclass implemented
+- [x] `save()` method accepts string or dict
+- [x] `save_raw()` method accepts explicit params
+- [x] API key from constructor or env var
+- [x] Base URL auto-detected from key prefix
+- [x] Error responses mapped to exception types
+- [x] Context manager support (`with` statement)
+- [x] Import works: `from surfacedocs import SurfaceDocs`

surfacedocs-0.1.0/AGENTS/DOCS_TASK.md

@@ -0,0 +1,345 @@
+# Task: Documentation
+
+## Status: COMPLETE
+
+## Objective
+
+Write user-facing documentation: README with examples, docstrings, and LICENSE.
+
+## Context
+
+- All code and tests complete
+- README is primary documentation (shown on PyPI)
+- Reference: `plans/python-sdk-spec.md`
+
+---
+
+## Deliverables
+
+1. `README.md` - Full documentation with examples
+2. Docstrings on all public APIs
+3. `LICENSE` - MIT license (verify exists)
+
+---
+
+## README.md
+
+```markdown
+# SurfaceDocs Python SDK
+
+Save LLM-generated documents to [SurfaceDocs](https://surfacedocs.dev).
+
+## Installation
+
+```bash
+pip install surfacedocs
+```
+
+## Quick Start
+
+```python
+from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT
+from openai import OpenAI
+
+# Initialize clients
+openai = OpenAI()
+docs = SurfaceDocs(api_key="sd_live_...")
+
+# Generate a document with your LLM
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": "Document our REST API authentication flow"},
+    ],
+    response_format={
+        "type": "json_schema",
+        "json_schema": {
+            "name": "surfacedocs_document",
+            "schema": DOCUMENT_SCHEMA,
+        },
+    },
+)
+
+# Save to SurfaceDocs
+result = docs.save(response.choices[0].message.content)
+print(result.url)  # https://app.surfacedocs.dev/d/abc123
+```
+
+## What's Included
+
+The SDK provides three exports:
+
+| Export | Type | Purpose |
+|--------|------|---------|
+| `DOCUMENT_SCHEMA` | dict | JSON schema for LLM structured output |
+| `SYSTEM_PROMPT` | str | Instructions for LLM to generate documents |
+| `SurfaceDocs` | class | HTTP client to save documents |
+
+## API Reference
+
+### SurfaceDocs
+
+```python
+from surfacedocs import SurfaceDocs
+
+# Initialize with API key
+client = SurfaceDocs(api_key="sd_live_...")
+
+# Or use environment variable
+# export SURFACEDOCS_API_KEY=sd_live_...
+client = SurfaceDocs()
+```
+
+#### save(content, folder_id=None)
+
+Save a document from LLM output.
+
+```python
+# From JSON string
+result = client.save(response.choices[0].message.content)
+
+# From dict
+result = client.save({
+    "title": "My Document",
+    "blocks": [{"type": "paragraph", "content": "Hello world"}]
+})
+
+# To specific folder
+result = client.save(content, folder_id="folder_abc123")
+```
+
+#### save_raw(title, blocks, folder_id=None, metadata=None)
+
+Save a document with explicit parameters.
+
+```python
+result = client.save_raw(
+    title="API Documentation",
+    blocks=[
+        {"type": "heading", "content": "Authentication", "metadata": {"level": 1}},
+        {"type": "paragraph", "content": "Use Bearer tokens for auth."},
+        {"type": "code", "content": "curl -H 'Authorization: Bearer ...'", "metadata": {"language": "bash"}},
+    ],
+    metadata={"source": "doc-generator", "version": "1.0"},
+)
+```
+
+#### SaveResult
+
+Both methods return a `SaveResult`:
+
+```python
+result.id        # "doc_abc123"
+result.url       # "https://app.surfacedocs.dev/d/doc_abc123"
+result.folder_id # "folder_xyz"
+```
+
+### DOCUMENT_SCHEMA
+
+JSON schema dict for LLM structured output. Pass directly to your LLM provider.
+
+```python
+from surfacedocs import DOCUMENT_SCHEMA
+
+# OpenAI
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[...],
+    response_format={
+        "type": "json_schema",
+        "json_schema": {
+            "name": "surfacedocs_document",
+            "schema": DOCUMENT_SCHEMA,
+        },
+    },
+)
+
+# Anthropic
+response = anthropic.messages.create(
+    model="claude-sonnet-4-20250514",
+    messages=[...],
+    tools=[{
+        "name": "create_document",
+        "description": "Create a structured document",
+        "input_schema": DOCUMENT_SCHEMA,
+    }],
+    tool_choice={"type": "tool", "name": "create_document"},
+)
+```
+
+### SYSTEM_PROMPT
+
+System prompt string to instruct LLMs on document format.
+
+```python
+from surfacedocs import SYSTEM_PROMPT
+
+messages = [
+    {"role": "system", "content": SYSTEM_PROMPT},
+    {"role": "user", "content": "Document the login flow"},
+]
+```
+
+## Block Types
+
+Documents are composed of blocks:
+
+| Type | Description | Metadata |
+|------|-------------|----------|
+| `heading` | Section header | `level` (1-6) |
+| `paragraph` | Body text | - |
+| `code` | Code block | `language` (optional) |
+| `list` | Bullet/numbered list | `listType` ("bullet" or "ordered") |
+| `quote` | Block quote | - |
+| `table` | Markdown table | - |
+| `image` | Image | `url` (required), `alt` (optional) |
+| `divider` | Horizontal rule | - |
+
+Text content supports inline markdown: `**bold**`, `*italic*`, `` `code` ``, `[link](url)`
+
+## Error Handling
+
+```python
+from surfacedocs import SurfaceDocs, SurfaceDocsError, AuthenticationError, ValidationError
+
+try:
+    result = client.save(content)
+except AuthenticationError:
+    print("Invalid API key")
+except ValidationError as e:
+    print(f"Invalid document: {e}")
+except SurfaceDocsError as e:
+    print(f"API error: {e}")
+```
+
+## Environment Variables
+
+```bash
+# API key (alternative to passing in code)
+export SURFACEDOCS_API_KEY=sd_live_...
+
+# Override base URL (for testing)
+export SURFACEDOCS_BASE_URL=https://ingress.dev.surfacedocs.dev
+```
+
+The SDK auto-detects environment from API key prefix:
+- `sd_live_*` → Production
+- `sd_test_*` → Development
+
+## Examples
+
+### OpenAI
+
+```python
+from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT
+from openai import OpenAI
+
+openai = OpenAI()
+docs = SurfaceDocs()
+
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": "Write documentation for user authentication"},
+    ],
+    response_format={
+        "type": "json_schema",
+        "json_schema": {"name": "document", "schema": DOCUMENT_SCHEMA},
+    },
+)
+
+result = docs.save(response.choices[0].message.content)
+print(f"Saved: {result.url}")
+```
+
+### Anthropic
+
+```python
+from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT
+import anthropic
+
+client = anthropic.Anthropic()
+docs = SurfaceDocs()
+
+response = client.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=4096,
+    system=SYSTEM_PROMPT,
+    messages=[
+        {"role": "user", "content": "Write documentation for user authentication"},
+    ],
+    tools=[{
+        "name": "create_document",
+        "description": "Create a structured document",
+        "input_schema": DOCUMENT_SCHEMA,
+    }],
+    tool_choice={"type": "tool", "name": "create_document"},
+)
+
+tool_use = next(b for b in response.content if b.type == "tool_use")
+result = docs.save(tool_use.input)
+print(f"Saved: {result.url}")
+```
+
+### Manual Document
+
+```python
+from surfacedocs import SurfaceDocs
+
+docs = SurfaceDocs()
+
+result = docs.save_raw(
+    title="Meeting Notes",
+    blocks=[
+        {"type": "heading", "content": "Action Items", "metadata": {"level": 1}},
+        {"type": "list", "content": "- Review PR #123\n- Update docs", "metadata": {"listType": "bullet"}},
+        {"type": "divider", "content": ""},
+        {"type": "paragraph", "content": "Next meeting: Monday 10am"},
+    ],
+    metadata={"source": "meeting-bot"},
+)
+```
+
+## License
+
+MIT
+```
+
+---
+
+## Docstrings
+
+Ensure all public APIs have docstrings:
+
+- `SurfaceDocs.__init__`
+- `SurfaceDocs.save`
+- `SurfaceDocs.save_raw`
+- `SaveResult` class
+- All exception classes
+- Module-level docstrings for `schema.py` and `prompt.py`
+
+---
+
+## Verification
+
+```bash
+# README renders correctly
+python -m readme_renderer README.md
+
+# Or just check it's valid markdown
+cat README.md
+```
+
+---
+
+## Definition of Done
+
+- [x] `README.md` with installation, quick start, API reference, examples
+- [x] OpenAI example in README
+- [x] Anthropic example in README
+- [x] Block types documented
+- [x] Error handling documented
+- [x] All public APIs have docstrings
+- [x] `LICENSE` file exists (MIT)