archastro.platform.v1.resources.extractions

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 0737f7cbe88e
  4
  5from __future__ import annotations
  6
  7from typing import Literal, Required, TypedDict
  8
  9from ...runtime.http_client import HttpClient, SyncHttpClient
 10from ...types.extractions import Extraction
 11
 12
 13class ExtractionCreateInput(TypedDict, total=False):
 14    "Start an extraction"
 15
 16    agent: str | None
 17    "Owning agent (`agt_...`) scopes the extraction and its outputs."
 18    destination_kind: Required[Literal["config", "storage"]]
 19    "Where outputs are written."
 20    destination_path: str | None
 21    "Destination virtual_path prefix. Required for `destination_kind=config`, where it must name at least one path segment (`.` and `..` segments are dropped)."
 22    file: str | None
 23    "Source file id (`fil_...`) for document extraction. Runs synchronously, so the source must be at most 10MB; larger files are rejected."
 24    max_pages: int | None
 25    "Crawl cap for `mode=site` must be at least 1 (defaults to 100; `link` is always 1)."
 26    mode: Literal["link", "site"] | None
 27    "Required with `url`. Document extraction is selected by `file` instead and takes no `mode` (its `kind` is `document`)."
 28    org: str | None
 29    "Owning organization (`org_...`). Defaults to the viewer's org."
 30    url: str | None
 31    "Source URL for link/site extraction."
 32
 33
 34class AsyncExtractionResource:
 35    def __init__(self, http: HttpClient):
 36        self._http = http
 37
 38    async def create(self, input: ExtractionCreateInput) -> Extraction:
 39        """
 40        Start an extraction
 41        Records a text-extraction job for a document (`file`) or a URL (`url` + `mode`).
 42        The job is owner-scoped and tagged with the caller-supplied `destination`
 43        namespace, **without** committing knowledge to an agent (no embeddings, no
 44        agent attach).
 45        Exactly one of `file` or (`url` + `mode`) is required.
 46        Document extraction (`file`) runs synchronously: the response already
 47        reflects the final state (`done` with its output, or an error if extraction
 48        couldn't complete), status `201`. URL extraction (`url` + `mode`) submits an
 49        async crawl and returns immediately with state `running`, status `202`
 50        poll `GET /extractions/:extraction` for its terminal state.
 51
 52        Args:
 53            input: Request body.
 54            input.agent: Owning agent (`agt_...`) scopes the extraction and its outputs.
 55            input.destination_kind: Where outputs are written.
 56            input.destination_path: Destination virtual_path prefix. Required for `destination_kind=config`, where it must name at least one path segment (`.` and `..` segments are dropped).
 57            input.file: Source file id (`fil_...`) for document extraction. Runs synchronously, so the source must be at most 10MB; larger files are rejected.
 58            input.max_pages: Crawl cap for `mode=site` must be at least 1 (defaults to 100; `link` is always 1).
 59            input.mode: Required with `url`. Document extraction is selected by `file` instead and takes no `mode` (its `kind` is `document`).
 60            input.org: Owning organization (`org_...`). Defaults to the viewer's org.
 61            input.url: Source URL for link/site extraction.
 62
 63        Returns:
 64            The extraction job. Document extraction returns `201` with `state: "done"`; link/site extraction returns `202` with `state: "running"`.
 65        """
 66        return await self._http.request(
 67            "/api/v1/extractions",
 68            method="POST",
 69            body=input,
 70            response_type=Extraction,
 71        )
 72
 73    async def get(self, extraction: str) -> Extraction:
 74        """
 75        Retrieve an extraction
 76        Returns a single extraction job and its current state. Poll this endpoint after
 77        starting an async (link/site) extraction until `state` is `done` or `failed`.
 78        An extraction that exists but is not visible to the current viewer returns `404`
 79        rather than `403`, so the resource's existence is not revealed.
 80
 81        Args:
 82            extraction: Extraction ID (`ext_...`).
 83
 84        Returns:
 85            The extraction job.
 86        """
 87        return await self._http.request(
 88            f"/api/v1/extractions/{extraction}",
 89            response_type=Extraction,
 90        )
 91
 92
 93class ExtractionResource:
 94    def __init__(self, http: SyncHttpClient):
 95        self._http = http
 96
 97    def create(self, input: ExtractionCreateInput) -> Extraction:
 98        """
 99        Start an extraction
100        Records a text-extraction job for a document (`file`) or a URL (`url` + `mode`).
101        The job is owner-scoped and tagged with the caller-supplied `destination`
102        namespace, **without** committing knowledge to an agent (no embeddings, no
103        agent attach).
104        Exactly one of `file` or (`url` + `mode`) is required.
105        Document extraction (`file`) runs synchronously: the response already
106        reflects the final state (`done` with its output, or an error if extraction
107        couldn't complete), status `201`. URL extraction (`url` + `mode`) submits an
108        async crawl and returns immediately with state `running`, status `202`
109        poll `GET /extractions/:extraction` for its terminal state.
110
111        Args:
112            input: Request body.
113            input.agent: Owning agent (`agt_...`) scopes the extraction and its outputs.
114            input.destination_kind: Where outputs are written.
115            input.destination_path: Destination virtual_path prefix. Required for `destination_kind=config`, where it must name at least one path segment (`.` and `..` segments are dropped).
116            input.file: Source file id (`fil_...`) for document extraction. Runs synchronously, so the source must be at most 10MB; larger files are rejected.
117            input.max_pages: Crawl cap for `mode=site` must be at least 1 (defaults to 100; `link` is always 1).
118            input.mode: Required with `url`. Document extraction is selected by `file` instead and takes no `mode` (its `kind` is `document`).
119            input.org: Owning organization (`org_...`). Defaults to the viewer's org.
120            input.url: Source URL for link/site extraction.
121
122        Returns:
123            The extraction job. Document extraction returns `201` with `state: "done"`; link/site extraction returns `202` with `state: "running"`.
124        """
125        return self._http.request(
126            "/api/v1/extractions",
127            method="POST",
128            body=input,
129            response_type=Extraction,
130        )
131
132    def get(self, extraction: str) -> Extraction:
133        """
134        Retrieve an extraction
135        Returns a single extraction job and its current state. Poll this endpoint after
136        starting an async (link/site) extraction until `state` is `done` or `failed`.
137        An extraction that exists but is not visible to the current viewer returns `404`
138        rather than `403`, so the resource's existence is not revealed.
139
140        Args:
141            extraction: Extraction ID (`ext_...`).
142
143        Returns:
144            The extraction job.
145        """
146        return self._http.request(f"/api/v1/extractions/{extraction}", response_type=Extraction)