apron-tools 0.1.0__py3-none-any.whl

apron_tools/__init__.py

@@ -0,0 +1,43 @@
+"""apron-tools: Agent-ready provider API wrappers.
+
+Curated tool definitions with typed schemas, OAuth scope mappings,
+and provider SDK wrappers for LLM function calling.
+"""
+
+from apron_tools.fileio import resolve_file_input
+from apron_tools.registry import (
+    discover_capability_groups,
+    discover_tools,
+    get_tools_for_provider,
+    get_tools_for_service,
+)
+from apron_tools.tool import tool
+from apron_tools.types import (
+    AccessType,
+    CapabilityGroup,
+    FileFromBytes,
+    FileFromUrl,
+    FileInput,
+    Scope,
+    ScopeMetadata,
+    ToolDefinition,
+    ToolResult,
+)
+
+__all__ = [
+    "AccessType",
+    "CapabilityGroup",
+    "FileFromBytes",
+    "FileFromUrl",
+    "FileInput",
+    "Scope",
+    "ScopeMetadata",
+    "ToolDefinition",
+    "ToolResult",
+    "discover_capability_groups",
+    "discover_tools",
+    "get_tools_for_provider",
+    "get_tools_for_service",
+    "resolve_file_input",
+    "tool",
+]

apron_tools/_utils.py

@@ -0,0 +1,26 @@
+"""Shared string utilities for provider tool implementations."""
+
+from __future__ import annotations
+
+
+def parse_csv_ids(value: str) -> list[str]:
+    """Split a comma-separated string into a list of non-empty, stripped tokens.
+
+    Args:
+        value: A comma-separated string (e.g. ``"abc,def , ghi"``).
+
+    Returns:
+        A list of stripped, non-empty strings.
+        Returns an empty list when *value* is empty or contains only whitespace.
+
+    Examples:
+        >>> parse_csv_ids("abc123,def456")
+        ['abc123', 'def456']
+        >>> parse_csv_ids("abc123, def456 , ghi789")
+        ['abc123', 'def456', 'ghi789']
+        >>> parse_csv_ids("")
+        []
+        >>> parse_csv_ids("  ,  ")
+        []
+    """
+    return [item.strip() for item in value.split(",") if item.strip()]

apron_tools/fileio.py

@@ -0,0 +1,75 @@
+"""Shared file I/O for resolving FileInput to raw bytes.
+
+Tools that accept file uploads use this module to normalise
+``FileFromUrl`` and ``FileFromBytes`` into a common
+``(bytes, filename, mime_type)`` tuple.
+"""
+
+from __future__ import annotations
+
+from email.message import Message
+from urllib.parse import unquote, urlparse
+
+import httpx
+
+from apron_tools.types import FileFromBytes, FileFromUrl, FileInput
+
+_TIMEOUT = 60.0
+
+
+async def resolve_file_input(file: FileInput) -> tuple[bytes, str, str]:
+    """Resolve a FileInput to raw bytes, filename, and MIME type.
+
+    For ``FileFromBytes``: returns the data directly.
+    For ``FileFromUrl``: downloads the URL and infers filename/MIME type
+    from the response headers when not explicitly provided.
+
+    .. warning:: Security consideration
+
+        When resolving a ``FileFromUrl``, the URL is fetched as-is with
+        no network filtering or size limits. See the warning on
+        ``FileFromUrl`` for details. Callers exposing this to untrusted
+        input should validate URLs before passing them here.
+
+    Args:
+        file: A ``FileFromUrl`` or ``FileFromBytes`` instance.
+
+    Returns:
+        A tuple of (bytes, filename, mime_type).
+
+    Raises:
+        httpx.HTTPStatusError: If the URL download fails.
+    """
+    if isinstance(file, FileFromBytes):
+        return file.data, file.filename, file.mime_type
+
+    return await _download_url(file)
+
+
+async def _download_url(file: FileFromUrl) -> tuple[bytes, str, str]:
+    """Download a file from a URL and infer metadata from the response."""
+    async with httpx.AsyncClient(timeout=_TIMEOUT, follow_redirects=True) as client:
+        resp = await client.get(str(file.url))
+        resp.raise_for_status()
+
+    data = resp.content
+
+    # Infer filename from explicit override, Content-Disposition, or URL path.
+    filename = file.filename
+    if not filename:
+        disposition = resp.headers.get("content-disposition", "")
+        if disposition:
+            msg = Message()
+            msg["content-disposition"] = disposition
+            # Prefer RFC 5987 filename* over plain filename.
+            raw = msg.get_param("filename*") or msg.get_filename() or ""
+            filename = str(raw) if raw else ""
+        if not filename:
+            filename = unquote(urlparse(str(file.url)).path.rsplit("/", 1)[-1]) or "download"
+
+    # Infer MIME type from explicit override or Content-Type header.
+    mime_type = file.mime_type
+    if not mime_type:
+        mime_type = resp.headers.get("content-type", "application/octet-stream").split(";")[0].strip()
+
+    return data, filename, mime_type

apron_tools/providers/__init__.py

@@ -0,0 +1 @@
+"""Provider subpackages for apron-tools."""

apron_tools/providers/atlassian/__init__.py

@@ -0,0 +1,6 @@
+"""Atlassian provider.
+
+API docs:
+  - Jira: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/
+  - Confluence: https://developer.atlassian.com/cloud/confluence/rest/v2/intro/
+"""

apron_tools/providers/atlassian/confluence/__init__.py

@@ -0,0 +1,4 @@
+"""Atlassian Confluence provider.
+
+API docs: https://developer.atlassian.com/cloud/confluence/rest/v2/intro/
+"""

apron_tools/providers/atlassian/confluence/scopes.py

@@ -0,0 +1,51 @@
+"""OAuth scope definitions for Atlassian Confluence tools."""
+
+from __future__ import annotations
+
+from apron_tools.types import CapabilityGroup, Scope
+
+
+class ConfluenceScope(Scope):
+    """OAuth scopes for Atlassian Confluence API access."""
+
+    READ_CONFLUENCE_CONTENT = (
+        "read:confluence-content.all",
+        "Read Content",
+        "View Confluence pages, blog posts, comments, and attachments across all spaces",
+        "read",
+        False,
+    )
+    WRITE_CONFLUENCE_CONTENT = (
+        "write:confluence-content",
+        "Write Content",
+        "Create and modify Confluence pages, blog posts, and attachments",
+        "write",
+        False,
+    )
+    SEARCH_CONFLUENCE = (
+        "search:confluence",
+        "Search",
+        "Search across Confluence content",
+        "read",
+        False,
+    )
+
+
+SCOPES: dict[str, list[ConfluenceScope]] = {
+    "atlassian_confluence_explore_spaces": [ConfluenceScope.READ_CONFLUENCE_CONTENT],
+    "atlassian_confluence_get_page_content": [ConfluenceScope.READ_CONFLUENCE_CONTENT],
+    "atlassian_confluence_create_page": [ConfluenceScope.WRITE_CONFLUENCE_CONTENT],
+    "atlassian_confluence_update_page": [
+        ConfluenceScope.READ_CONFLUENCE_CONTENT,
+        ConfluenceScope.WRITE_CONFLUENCE_CONTENT,
+    ],
+    "atlassian_confluence_search_content": [ConfluenceScope.SEARCH_CONFLUENCE],
+    "atlassian_confluence_get_child_pages": [ConfluenceScope.READ_CONFLUENCE_CONTENT],
+    "atlassian_confluence_upload_attachment": [ConfluenceScope.WRITE_CONFLUENCE_CONTENT],
+}
+
+CAPABILITY_GROUP = CapabilityGroup(
+    provider="atlassian_confluence",
+    display_name="Atlassian Confluence",
+    scopes=sorted({s for scopes in SCOPES.values() for s in scopes}),
+)

apron_tools/providers/atlassian/confluence/tools.py

@@ -0,0 +1,433 @@
+"""Atlassian Confluence tool functions for interacting with the Confluence REST API."""
+
+from __future__ import annotations
+
+import httpx
+
+from apron_tools.fileio import resolve_file_input
+from apron_tools.providers.atlassian.confluence.types import (
+    ChildPageSummary,
+    CreatePageParams,
+    CreatePageResult,
+    ExploreSpacesParams,
+    ExploreSpacesResult,
+    GetChildPagesParams,
+    GetChildPagesResult,
+    GetPageContentParams,
+    GetPageContentResult,
+    PageSummary,
+    SearchContentParams,
+    SearchContentResult,
+    SearchResult,
+    SpaceSummary,
+    UpdatePageParams,
+    UpdatePageResult,
+    UploadAttachmentParams,
+    UploadAttachmentResult,
+)
+from apron_tools.tool import tool
+
+from .scopes import SCOPES
+
+_BASE_URL = "https://api.atlassian.com"
+_TIMEOUT = 60.0
+
+
+def _headers(token: str, *, content_type: bool = False) -> dict[str, str]:
+    """Build authorization headers for a Confluence API request."""
+    h: dict[str, str] = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+    }
+    if content_type:
+        h["Content-Type"] = "application/json"
+    return h
+
+
+async def _resolve_cloud_id(token: str, base_url: str) -> str | None:
+    """Resolve the Confluence cloud ID for the authenticated user.
+
+    Atlassian cloud APIs require a cloud ID to construct API URLs. This
+    calls the accessible-resources endpoint to retrieve it.
+    """
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            resp = await client.get(
+                f"{base_url}/oauth/token/accessible-resources",
+                headers=_headers(token),
+            )
+            if resp.is_success:
+                resources = resp.json()
+                if resources:
+                    return resources[0].get("id")
+    except httpx.HTTPError:
+        pass
+    return None
+
+
+def _api_v2_url(cloud_id: str, path: str, *, base_url: str) -> str:
+    """Build a Confluence REST API v2 URL."""
+    return f"{base_url}/ex/confluence/{cloud_id}/wiki/api/v2{path}"
+
+
+def _api_v1_url(cloud_id: str, path: str, *, base_url: str) -> str:
+    """Build a Confluence REST API v1 URL."""
+    return f"{base_url}/ex/confluence/{cloud_id}/wiki/rest/api{path}"
+
+
+@tool(
+    scopes=SCOPES["atlassian_confluence_explore_spaces"],
+    api_docs="https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-space/#api-wiki-api-v2-spaces-get",
+    provider="atlassian",
+    service="atlassian_confluence",
+)
+async def atlassian_confluence_explore_spaces(
+    params: ExploreSpacesParams,
+    *,
+    token: str,
+    base_url: str = _BASE_URL,
+) -> ExploreSpacesResult:
+    """List all Confluence spaces accessible to the authenticated user."""
+    cloud_id = await _resolve_cloud_id(token, base_url)
+    if not cloud_id:
+        return ExploreSpacesResult(
+            success=False,
+            error="Failed to resolve Confluence cloud ID. Ensure you have access to a Confluence site.",
+        )
+
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            resp = await client.get(
+                _api_v2_url(cloud_id, "/spaces", base_url=base_url),
+                headers=_headers(token),
+                params={"limit": params.max_results},
+            )
+    except httpx.HTTPError as exc:
+        return ExploreSpacesResult(success=False, error=str(exc))
+
+    if not resp.is_success:
+        return ExploreSpacesResult(
+            success=False,
+            error=f"Confluence API error {resp.status_code}: {resp.text}",
+        )
+
+    data = resp.json()
+    spaces = [SpaceSummary.model_validate(s) for s in data.get("results", [])]
+    return ExploreSpacesResult(success=True, spaces=spaces)
+
+
+@tool(
+    scopes=SCOPES["atlassian_confluence_get_page_content"],
+    api_docs="https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-page/#api-wiki-api-v2-pages-id-get",
+    provider="atlassian",
+    service="atlassian_confluence",
+)
+async def atlassian_confluence_get_page_content(
+    params: GetPageContentParams,
+    *,
+    token: str,
+    base_url: str = _BASE_URL,
+) -> GetPageContentResult:
+    """Retrieve a Confluence page by ID, including its storage-format body."""
+    cloud_id = await _resolve_cloud_id(token, base_url)
+    if not cloud_id:
+        return GetPageContentResult(
+            success=False,
+            error="Failed to resolve Confluence cloud ID. Ensure you have access to a Confluence site.",
+        )
+
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            resp = await client.get(
+                _api_v2_url(cloud_id, f"/pages/{params.page_id}", base_url=base_url),
+                headers=_headers(token),
+                params={"body-format": "storage"},
+            )
+    except httpx.HTTPError as exc:
+        return GetPageContentResult(success=False, error=str(exc))
+
+    if not resp.is_success:
+        return GetPageContentResult(
+            success=False,
+            error=f"Confluence API error {resp.status_code}: {resp.text}",
+        )
+
+    page = PageSummary.model_validate(resp.json())
+    return GetPageContentResult(success=True, page=page)
+
+
+@tool(
+    scopes=SCOPES["atlassian_confluence_create_page"],
+    api_docs="https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-page/#api-wiki-api-v2-pages-post",
+    provider="atlassian",
+    service="atlassian_confluence",
+)
+async def atlassian_confluence_create_page(
+    params: CreatePageParams,
+    *,
+    token: str,
+    base_url: str = _BASE_URL,
+) -> CreatePageResult:
+    """Create a new Confluence page."""
+    cloud_id = await _resolve_cloud_id(token, base_url)
+    if not cloud_id:
+        return CreatePageResult(
+            success=False,
+            error="Failed to resolve Confluence cloud ID. Ensure you have access to a Confluence site.",
+        )
+
+    payload: dict = {
+        "spaceId": params.space_id,
+        "status": params.status,
+        "title": params.title,
+        "body": {
+            "representation": "storage",
+            "value": params.body,
+        },
+    }
+    if params.parent_id:
+        payload["parentId"] = params.parent_id
+
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            resp = await client.post(
+                _api_v2_url(cloud_id, "/pages", base_url=base_url),
+                headers=_headers(token, content_type=True),
+                json=payload,
+            )
+    except httpx.HTTPError as exc:
+        return CreatePageResult(success=False, error=str(exc))
+
+    if not resp.is_success:
+        return CreatePageResult(
+            success=False,
+            error=f"Confluence API error {resp.status_code}: {resp.text}",
+        )
+
+    page = PageSummary.model_validate(resp.json())
+    return CreatePageResult(success=True, page=page)
+
+
+@tool(
+    scopes=SCOPES["atlassian_confluence_update_page"],
+    api_docs="https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-page/#api-wiki-api-v2-pages-id-get",
+    provider="atlassian",
+    service="atlassian_confluence",
+)
+async def atlassian_confluence_update_page(
+    params: UpdatePageParams,
+    *,
+    token: str,
+    base_url: str = _BASE_URL,
+) -> UpdatePageResult:
+    """Update an existing Confluence page.
+
+    Fetches the current version number first, then sends the update with
+    version incremented by one.
+    """
+    cloud_id = await _resolve_cloud_id(token, base_url)
+    if not cloud_id:
+        return UpdatePageResult(
+            success=False,
+            error="Failed to resolve Confluence cloud ID. Ensure you have access to a Confluence site.",
+        )
+
+    # Fetch current page to get the version number.
+    page_url = _api_v2_url(cloud_id, f"/pages/{params.page_id}", base_url=base_url)
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            get_resp = await client.get(
+                page_url,
+                headers=_headers(token),
+            )
+    except httpx.HTTPError as exc:
+        return UpdatePageResult(success=False, error=str(exc))
+
+    if not get_resp.is_success:
+        return UpdatePageResult(
+            success=False,
+            error=f"Confluence API error {get_resp.status_code}: {get_resp.text}",
+        )
+
+    current_data = get_resp.json()
+    current_version = current_data.get("version", {}).get("number", 0)
+
+    payload = {
+        "id": params.page_id,
+        "status": params.status,
+        "title": params.title,
+        "body": {
+            "representation": "storage",
+            "value": params.body,
+        },
+        "version": {
+            "number": current_version + 1,
+            "message": "",
+        },
+    }
+
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            put_resp = await client.put(
+                page_url,
+                headers=_headers(token, content_type=True),
+                json=payload,
+            )
+    except httpx.HTTPError as exc:
+        return UpdatePageResult(success=False, error=str(exc))
+
+    if not put_resp.is_success:
+        return UpdatePageResult(
+            success=False,
+            error=f"Confluence API error {put_resp.status_code}: {put_resp.text}",
+        )
+
+    page = PageSummary.model_validate(put_resp.json())
+    return UpdatePageResult(success=True, page=page)
+
+
+@tool(
+    scopes=SCOPES["atlassian_confluence_search_content"],
+    api_docs="https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-search/#api-wiki-rest-api-search-get",
+    provider="atlassian",
+    service="atlassian_confluence",
+)
+async def atlassian_confluence_search_content(
+    params: SearchContentParams,
+    *,
+    token: str,
+    base_url: str = _BASE_URL,
+) -> SearchContentResult:
+    """Search Confluence content using CQL (Confluence Query Language)."""
+    cloud_id = await _resolve_cloud_id(token, base_url)
+    if not cloud_id:
+        return SearchContentResult(
+            success=False,
+            error="Failed to resolve Confluence cloud ID. Ensure you have access to a Confluence site.",
+        )
+
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            resp = await client.get(
+                _api_v1_url(cloud_id, "/search", base_url=base_url),
+                headers=_headers(token),
+                params={"cql": params.cql, "limit": params.limit},
+            )
+    except httpx.HTTPError as exc:
+        return SearchContentResult(success=False, error=str(exc))
+
+    if not resp.is_success:
+        return SearchContentResult(
+            success=False,
+            error=f"Confluence API error {resp.status_code}: {resp.text}",
+        )
+
+    data = resp.json()
+    results = [SearchResult.model_validate(r) for r in data.get("results", [])]
+    return SearchContentResult(
+        success=True,
+        results=results,
+        total_size=data.get("totalSize", len(results)),
+        cql_query=data.get("cqlQuery", params.cql),
+    )
+
+
+@tool(
+    scopes=SCOPES["atlassian_confluence_get_child_pages"],
+    api_docs="https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-children/#api-pages-id-direct-children-get",
+    provider="atlassian",
+    service="atlassian_confluence",
+)
+async def atlassian_confluence_get_child_pages(
+    params: GetChildPagesParams,
+    *,
+    token: str,
+    base_url: str = _BASE_URL,
+) -> GetChildPagesResult:
+    """List direct child pages of a Confluence page."""
+    cloud_id = await _resolve_cloud_id(token, base_url)
+    if not cloud_id:
+        return GetChildPagesResult(
+            success=False,
+            error="Failed to resolve Confluence cloud ID. Ensure you have access to a Confluence site.",
+        )
+
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            resp = await client.get(
+                _api_v2_url(
+                    cloud_id,
+                    f"/pages/{params.page_id}/direct-children",
+                    base_url=base_url,
+                ),
+                headers=_headers(token),
+            )
+    except httpx.HTTPError as exc:
+        return GetChildPagesResult(success=False, error=str(exc))
+
+    if not resp.is_success:
+        return GetChildPagesResult(
+            success=False,
+            error=f"Confluence API error {resp.status_code}: {resp.text}",
+        )
+
+    data = resp.json()
+    children = [ChildPageSummary.model_validate(c) for c in data.get("results", [])]
+    return GetChildPagesResult(success=True, children=children)
+
+
+@tool(
+    scopes=SCOPES["atlassian_confluence_upload_attachment"],
+    api_docs="https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content-attachments/",
+    provider="atlassian",
+    service="atlassian_confluence",
+)
+async def atlassian_confluence_upload_attachment(
+    params: UploadAttachmentParams,
+    *,
+    token: str,
+    base_url: str = _BASE_URL,
+) -> UploadAttachmentResult:
+    """Upload a file as an attachment to a Confluence page."""
+    try:
+        data, filename, mime_type = await resolve_file_input(params.file)
+    except Exception as exc:
+        return UploadAttachmentResult(success=False, error=f"Failed to resolve file: {exc}")
+
+    cloud_id = await _resolve_cloud_id(token, base_url)
+    if not cloud_id:
+        return UploadAttachmentResult(
+            success=False,
+            error="Failed to resolve Confluence cloud ID. Ensure you have access to a Confluence site.",
+        )
+
+    url = _api_v1_url(cloud_id, f"/content/{params.page_id}/child/attachment", base_url=base_url)
+    headers = _headers(token)
+    headers["X-Atlassian-Token"] = "no-check"
+
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            resp = await client.post(
+                url,
+                headers=headers,
+                files={"file": (filename, data, mime_type)},
+            )
+    except httpx.HTTPError as exc:
+        return UploadAttachmentResult(success=False, error=str(exc))
+
+    if not resp.is_success:
+        return UploadAttachmentResult(
+            success=False,
+            error=f"Confluence API error {resp.status_code}: {resp.text}",
+        )
+
+    results = resp.json().get("results", [])
+    attachment_id = results[0].get("id", "") if results else ""
+    att_filename = results[0].get("title", filename) if results else filename
+
+    return UploadAttachmentResult(
+        success=True,
+        attachment_id=attachment_id,
+        filename=att_filename,
+        page_id=params.page_id,
+    )