doconda 0.1.0__tar.gz

doconda-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# turbo
+.turbo
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# typescript
+*.tsbuildinfo
+
+# python
+.venv
+__pycache__
+.pytest_cache
+.ruff_cache
+
+# next
+.next
+out
+next-env.d.ts
+
+# ===== Infra =====
+infra/**/.terraform/
+*.tfstate
+*.tfstate.*
+sensitive.auto.tfvars.json
+ci.auto.tfvars.json
+backend.hcl
+
+# SlidesCarnival originals (large): see engine/themes/README.md
+engine/themes/sources/
+
+# Local template library (large, not in git)
+/library/
+infra/**/.build/
+evals/.cache/
+evals/runs/
+evals/.venv/
+evals/.env
+evals/manual/

doconda-0.1.0/LICENSE

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

doconda-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: doconda
+Version: 0.1.0
+Summary: Python SDK for Doconda: generate, review and edit Word, PowerPoint, Excel and PDF documents from AI agents (Amazon Bedrock, Vertex AI, OpenAI, Claude, LangChain).
+Project-URL: Homepage, https://doconda.com
+Project-URL: Documentation, https://docs.doconda.com/en/sdk/python
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,anthropic,bedrock,document-generation,docx,excel,langchain,llm,mcp,openai,pdf,powerpoint,pptx,tools,vertex-ai,word,xlsx
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# doconda
+
+Generate, review and edit **Word (DOCX), PowerPoint (PPTX), Excel (XLSX) and PDF** documents from your AI agent or chatbot, with one call. Editable files with real Word styles, reviewed before they are delivered.
+
+Use it when your agent has to hand the user a document and you don't want to maintain python-docx, python-pptx, openpyxl or templates. Works with Amazon Bedrock, Vertex AI, OpenAI, Claude, Gemini, LangChain, CrewAI and any model with tool calling.
+
+```bash
+pip install doconda
+```
+
+```python
+from doconda import Doconda
+
+doconda = Doconda()  # reads DOCONDA_API_KEY
+doc = doconda.documents.create(format="docx", prompt="Report on the housing law")
+print(doc["outputs"])  # links to the Word file and the PDF
+
+open("report.docx", "wb").write(doconda.documents.download(doc["id"], "docx"))
+```
+
+## As tools for your agent
+
+`doconda.tools()` returns ready-made tools (name, description, JSON Schema, `run`) to create, review and edit documents. With Amazon Bedrock (Converse API):
+
+```python
+import json
+import boto3
+from doconda import Doconda
+
+bedrock = boto3.client("bedrock-runtime")
+tools = Doconda().tools()
+tool_config = {
+    "tools": [
+        {"toolSpec": {"name": t.name, "description": t.description, "inputSchema": {"json": t.input_schema}}}
+        for t in tools
+    ]
+}
+messages = [{"role": "user", "content": [{"text": "Make an Excel with the event budget"}]}]
+
+while True:
+    res = bedrock.converse(modelId=MODEL_ID, messages=messages, toolConfig=tool_config)
+    message = res["output"]["message"]
+    messages.append(message)
+    if res["stopReason"] != "tool_use":
+        break
+    results = []
+    for block in message["content"]:
+        if "toolUse" in block:
+            use = block["toolUse"]
+            out = next(t for t in tools if t.name == use["name"]).run(use["input"])
+            results.append(
+                {"toolResult": {"toolUseId": use["toolUseId"], "content": [{"text": json.dumps(out)}]}}
+            )
+    messages.append({"role": "user", "content": results})
+```
+
+The same tools plug into Vertex AI / Gemini, OpenAI, Claude, LangChain or CrewAI: see the guides.
+
+## What else
+
+- `documents.create(operation="review", file=…)` and `operation="edit"`: review and fix, or change, an existing Word, PowerPoint, Excel or PDF.
+- `documents.stream(…)`: the document's events as they happen.
+- `extract(file)`: any file to Markdown for your model (free).
+- `files.upload(path_or_bytes)`, `webhooks.create(url)` and `verify_webhook(body, headers, secret)`.
+
+Docs: https://docs.doconda.com/en/sdk/python · Guides per stack: https://docs.doconda.com/en/agents/introduction · Get an API key: https://doconda.com

doconda-0.1.0/README.md

@@ -0,0 +1,66 @@
+# doconda
+
+Generate, review and edit **Word (DOCX), PowerPoint (PPTX), Excel (XLSX) and PDF** documents from your AI agent or chatbot, with one call. Editable files with real Word styles, reviewed before they are delivered.
+
+Use it when your agent has to hand the user a document and you don't want to maintain python-docx, python-pptx, openpyxl or templates. Works with Amazon Bedrock, Vertex AI, OpenAI, Claude, Gemini, LangChain, CrewAI and any model with tool calling.
+
+```bash
+pip install doconda
+```
+
+```python
+from doconda import Doconda
+
+doconda = Doconda()  # reads DOCONDA_API_KEY
+doc = doconda.documents.create(format="docx", prompt="Report on the housing law")
+print(doc["outputs"])  # links to the Word file and the PDF
+
+open("report.docx", "wb").write(doconda.documents.download(doc["id"], "docx"))
+```
+
+## As tools for your agent
+
+`doconda.tools()` returns ready-made tools (name, description, JSON Schema, `run`) to create, review and edit documents. With Amazon Bedrock (Converse API):
+
+```python
+import json
+import boto3
+from doconda import Doconda
+
+bedrock = boto3.client("bedrock-runtime")
+tools = Doconda().tools()
+tool_config = {
+    "tools": [
+        {"toolSpec": {"name": t.name, "description": t.description, "inputSchema": {"json": t.input_schema}}}
+        for t in tools
+    ]
+}
+messages = [{"role": "user", "content": [{"text": "Make an Excel with the event budget"}]}]
+
+while True:
+    res = bedrock.converse(modelId=MODEL_ID, messages=messages, toolConfig=tool_config)
+    message = res["output"]["message"]
+    messages.append(message)
+    if res["stopReason"] != "tool_use":
+        break
+    results = []
+    for block in message["content"]:
+        if "toolUse" in block:
+            use = block["toolUse"]
+            out = next(t for t in tools if t.name == use["name"]).run(use["input"])
+            results.append(
+                {"toolResult": {"toolUseId": use["toolUseId"], "content": [{"text": json.dumps(out)}]}}
+            )
+    messages.append({"role": "user", "content": results})
+```
+
+The same tools plug into Vertex AI / Gemini, OpenAI, Claude, LangChain or CrewAI: see the guides.
+
+## What else
+
+- `documents.create(operation="review", file=…)` and `operation="edit"`: review and fix, or change, an existing Word, PowerPoint, Excel or PDF.
+- `documents.stream(…)`: the document's events as they happen.
+- `extract(file)`: any file to Markdown for your model (free).
+- `files.upload(path_or_bytes)`, `webhooks.create(url)` and `verify_webhook(body, headers, secret)`.
+
+Docs: https://docs.doconda.com/en/sdk/python · Guides per stack: https://docs.doconda.com/en/agents/introduction · Get an API key: https://doconda.com

doconda-0.1.0/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@doconda/sdk-python",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Thin wrapper so turbo runs the Python SDK's checks. The SDK itself is managed with uv.",
+  "scripts": {
+    "test": "uv run pytest -q",
+    "lint": "uv run ruff check . && uv run ruff format --check ."
+  }
+}

doconda-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "doconda"
+version = "0.1.0"
+description = "Python SDK for Doconda: generate, review and edit Word, PowerPoint, Excel and PDF documents from AI agents (Amazon Bedrock, Vertex AI, OpenAI, Claude, LangChain)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.27"]
+keywords = [
+  "docx", "pptx", "xlsx", "pdf", "word", "powerpoint", "excel", "document-generation", "ai-agents", "llm",
+  "tools", "bedrock", "vertex-ai", "openai", "anthropic", "langchain", "mcp",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Office/Business",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://doconda.com"
+Documentation = "https://docs.doconda.com/en/sdk/python"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.12"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 110
+target-version = "py39"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

doconda-0.1.0/src/doconda/__init__.py

@@ -0,0 +1,6 @@
+from ._client import Doconda, DocondaError, verify_webhook
+from ._tools import Tool
+
+# ===== Public API =====
+
+__all__ = ["Doconda", "DocondaError", "Tool", "verify_webhook"]

doconda-0.1.0/src/doconda/_client.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import re
+import time
+import uuid
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+from typing import IO, Any, Union
+from urllib.parse import quote
+
+import httpx
+
+# ===== Types =====
+
+FileLike = Union[str, bytes, os.PathLike, IO[bytes]]
+
+# ===== Constants =====
+
+TERMINAL = {"ready", "ready_with_warnings", "needs_review", "failed", "canceled"}
+TERMINAL_EVENTS = {"document.ready", "document.failed", "document.canceled"}
+TIMEOUT = httpx.Timeout(60.0, read=600.0)
+STREAM_TIMEOUT = httpx.Timeout(60.0, read=None)
+
+# ===== Helpers =====
+
+
+def _sse(response: httpx.Response) -> Iterator[dict]:
+    data: list[str] = []
+    for line in response.iter_lines():
+        if not line:
+            if data:
+                yield json.loads("\n".join(data))
+            data = []
+        elif line.startswith("data:"):
+            data.append(line[5:].removeprefix(" "))
+    if data:
+        yield json.loads("\n".join(data))
+
+
+def _read(file: FileLike, filename: str | None) -> tuple[bytes, str]:
+    if isinstance(file, bytes):
+        if not filename:
+            raise ValueError("Doconda: pass filename (with its extension) when uploading bytes.")
+        return file, filename
+    if isinstance(file, (str, os.PathLike)):
+        path = Path(file)
+        return path.read_bytes(), filename or path.name
+    name = filename or Path(getattr(file, "name", "") or "").name
+    if not name:
+        raise ValueError("Doconda: pass filename (with its extension) for this file object.")
+    return file.read(), name
+
+
+def _file_input(file: FileLike | Mapping[str, str], filename: str | None) -> Any:
+    if isinstance(file, Mapping):
+        return dict(file)
+    if isinstance(file, str) and re.match(r"^(file|doc)_", file):
+        return file
+    if isinstance(file, str) and re.match(r"^https?://", file):
+        return {"url": file, **({"filename": filename} if filename else {})}
+    data, name = _read(file, filename)
+    return {"data": base64.b64encode(data).decode(), "filename": name}
+
+
+def _query(params: Mapping[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None}
+
+
+# ===== Public API =====
+
+
+class DocondaError(Exception):
+    def __init__(self, status: int, body: Any):
+        body = body if isinstance(body, dict) else {}
+        super().__init__(body.get("title") or f"Doconda API answered {status}")
+        self.status = status
+        self.code = body.get("code") or "http_error"
+        self.request_id = body.get("request_id")
+        self.errors = body.get("errors") or []
+
+
+class Doconda:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ):
+        key = api_key or os.environ.get("DOCONDA_API_KEY")
+        if not key:
+            raise ValueError("Doconda: pass api_key or set DOCONDA_API_KEY.")
+        self.base_url = (
+            base_url or os.environ.get("DOCONDA_BASE_URL") or "https://api.eu.doconda.com/v1"
+        ).rstrip("/")
+        self.max_retries = max_retries
+        self._key = key
+        self._http = http_client or httpx.Client(timeout=TIMEOUT)
+        self.documents = Documents(self)
+        self.files = Files(self)
+        self.webhooks = Webhooks(self)
+
+    def tools(self, *, local_files: bool = False) -> list:
+        from ._tools import doconda_tools
+
+        return doconda_tools(self, local_files=local_files)
+
+    def extract(self, file: FileLike | Mapping[str, str], *, filename: str | None = None) -> dict:
+        result = self.json("POST", "/extract", json={"file": _file_input(file, filename)})
+        while "markdown" not in result:
+            time.sleep(2)
+            result = self.json("GET", f"/extract/{result['id']}")
+        return result
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        files: Any = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        stream: bool = False,
+    ) -> httpx.Response:
+        all_headers = {"authorization": f"Bearer {self._key}", **(headers or {})}
+        for attempt in range(self.max_retries + 1):
+            try:
+                request = self._http.build_request(
+                    method,
+                    f"{self.base_url}{path}",
+                    json=json,
+                    files=files,
+                    params=params,
+                    headers=all_headers,
+                    timeout=STREAM_TIMEOUT if stream else self._http.timeout,
+                )
+                response = self._http.send(request, stream=stream)
+            except httpx.TransportError:
+                if attempt >= self.max_retries:
+                    raise
+                time.sleep(0.5 * 2**attempt)
+                continue
+            if response.is_success:
+                return response
+            if stream:
+                response.read()
+            retryable = response.status_code == 429 or response.status_code >= 500
+            if not retryable or attempt >= self.max_retries:
+                try:
+                    body = response.json()
+                except ValueError:
+                    body = None
+                raise DocondaError(response.status_code, body)
+            wait = response.headers.get("retry-after")
+            time.sleep(float(wait) if wait and wait.isdigit() else 0.5 * 2**attempt)
+        raise AssertionError("unreachable")
+
+    def json(self, method: str, path: str, **kwargs: Any) -> Any:
+        response = self.request(method, path, **kwargs)
+        return None if response.status_code == 204 else response.json()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class Documents:
+    def __init__(self, client: Doconda):
+        self._c = client
+
+    def create(self, *, idempotency_key: str | None = None, **body: Any) -> dict:
+        doc = self._post(body, idempotency_key)
+        return doc if doc["status"] in TERMINAL else self.wait(doc["id"])
+
+    def create_in_background(self, *, idempotency_key: str | None = None, **body: Any) -> dict:
+        return self._post({**body, "background": True}, idempotency_key)
+
+    def stream(self, *, idempotency_key: str | None = None, **body: Any) -> Iterator[dict]:
+        response = self._c.request(
+            "POST",
+            "/documents",
+            json={**body, "stream": True},
+            headers={"idempotency-key": idempotency_key or str(uuid.uuid4()), "accept": "text/event-stream"},
+            stream=True,
+        )
+        try:
+            yield from _sse(response)
+        finally:
+            response.close()
+
+    def get(self, document_id: str) -> dict:
+        return self._c.json("GET", f"/documents/{document_id}")
+
+    def page(self, *, limit: int | None = None, cursor: str | None = None, status: str | None = None) -> dict:
+        return self._c.json(
+            "GET", "/documents", params=_query({"limit": limit, "cursor": cursor, "status": status})
+        )
+
+    def list(self, *, status: str | None = None) -> Iterator[dict]:
+        cursor = None
+        while True:
+            page = self.page(limit=100, cursor=cursor, status=status)
+            yield from page["data"]
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+
+    def cancel(self, document_id: str) -> dict:
+        return self._c.json(
+            "POST", f"/documents/{document_id}/cancel", headers={"idempotency-key": str(uuid.uuid4())}
+        )
+
+    def delete(self, document_id: str) -> None:
+        self._c.json("DELETE", f"/documents/{document_id}")
+
+    def events(self, document_id: str, *, after: int = 0) -> Iterator[dict]:
+        response = self._c.request(
+            "GET", f"/documents/{document_id}/events", params=_query({"after": after or None}), stream=True
+        )
+        try:
+            yield from _sse(response)
+        finally:
+            response.close()
+
+    def wait(self, document_id: str) -> dict:
+        after = 0
+        while True:
+            for event in self.events(document_id, after=after):
+                after = event["sequence"]
+                if event["type"] in TERMINAL_EVENTS:
+                    return self.get(document_id)
+            doc = self.get(document_id)
+            if doc["status"] in TERMINAL:
+                return doc
+
+    def outputs(self, document_id: str) -> list:
+        return self._c.json("GET", f"/documents/{document_id}/outputs")["data"]
+
+    def download(self, document_id: str, kind: str) -> bytes:
+        output = next((o for o in self.outputs(document_id) if o["kind"] == kind), None)
+        if output is None:
+            raise ValueError(f"Doconda: document {document_id} has no {kind}.")
+        response = httpx.get(output["url"], timeout=TIMEOUT, follow_redirects=True)
+        response.raise_for_status()
+        return response.content
+
+    def report(self, document_id: str) -> dict:
+        return self._c.json("GET", f"/documents/{document_id}/report")
+
+    def data(self, document_id: str, collection: str | None = None) -> list:
+        path = f"/documents/{document_id}/data" + (f"/{quote(collection, safe='')}" if collection else "")
+        return self._c.json("GET", path)["data"]
+
+    def _post(self, body: dict, idempotency_key: str | None) -> dict:
+        return self._c.json(
+            "POST", "/documents", json=body, headers={"idempotency-key": idempotency_key or str(uuid.uuid4())}
+        )
+
+
+class Files:
+    def __init__(self, client: Doconda):
+        self._c = client
+
+    def upload(self, file: FileLike, filename: str | None = None) -> dict:
+        data, name = _read(file, filename)
+        return self._c.json("POST", "/files", files={"file": (name, data)})
+
+    def get(self, file_id: str) -> dict:
+        return self._c.json("GET", f"/files/{file_id}")
+
+    def delete(self, file_id: str) -> None:
+        self._c.json("DELETE", f"/files/{file_id}")
+
+
+class Webhooks:
+    def __init__(self, client: Doconda):
+        self._c = client
+
+    def create(self, url: str, *, event_types: list[str] | None = None) -> dict:
+        return self._c.json(
+            "POST", "/webhook-endpoints", json=_query({"url": url, "event_types": event_types})
+        )
+
+    def list(self) -> list:
+        return self._c.json("GET", "/webhook-endpoints")["data"]
+
+    def delete(self, endpoint_id: str) -> None:
+        self._c.json("DELETE", f"/webhook-endpoints/{endpoint_id}")
+
+
+def verify_webhook(
+    body: str | bytes, headers: Mapping[str, str], secret: str, tolerance_seconds: int = 300
+) -> dict:
+    lower = {k.lower(): v for k, v in headers.items()}
+    msg_id, timestamp, signatures = (
+        lower.get(h) for h in ("webhook-id", "webhook-timestamp", "webhook-signature")
+    )
+    if not msg_id or not timestamp or not signatures:
+        raise ValueError("Doconda webhook: missing webhook-id, -timestamp or -signature.")
+    if abs(time.time() - int(timestamp)) > tolerance_seconds:
+        raise ValueError("Doconda webhook: the timestamp is too old or in the future.")
+    text = body.decode() if isinstance(body, bytes) else body
+    key = base64.b64decode(secret.removeprefix("whsec_"))
+    mac = hmac.new(key, f"{msg_id}.{timestamp}.{text}".encode(), hashlib.sha256).digest()
+    expected = base64.b64encode(mac).decode()
+    if not any(s.startswith("v1,") and hmac.compare_digest(s[3:], expected) for s in signatures.split(" ")):
+        raise ValueError("Doconda webhook: the signature does not match.")
+    return json.loads(text)