docu-devs-api-client 1.11.0__tar.gz → 1.12.1__tar.gz

{docu_devs_api_client-1.11.0 → docu_devs_api_client-1.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docu-devs-api-client
-Version: 1.11.0
+Version: 1.12.1
 Summary: A client library for accessing DocuDevs API
 Project-URL: Homepage, https://www.docudevs.ai/
 Project-URL: Repository, https://github.com/piizei/docudevs.git
@@ -49,6 +49,38 @@ Use `propose_contract_analysis_finding_test_case(...)` to turn one captured find
 pip install docu-devs-api-client
 ```
 
+## Case records
+
+Create a records case, load rows, and classify them against a category tree. Long-running calls return a job handle; the `*_and_wait` variants block until the job finishes.
+
+```python
+import os
+
+from docudevs import DocuDevsClient
+
+api = DocuDevsClient(token=os.environ["DOCUDEVS_API_KEY"])
+case = await api.create_records_case(
+    "Product classification",
+    key="ean",
+    text=["name", "generic_name", "ingredients"],
+    label="leaf",
+    metadata=["brand"],
+    target_depth=[1, 2, 3],
+)
+await case.import_records_and_wait(rows)  # dicts keyed by the field names above
+await case.set_tree_and_wait(nodes, name="Taxonomy v1")
+
+job = await case.classify_and_wait(keys=["4001", "4002"], llm_level="MINI")
+for row in await job.flagged():
+    await row.accept()  # or row.correct("4.1.2", reason="...") / row.feedback("...")
+
+await case.memo.add("Oat drinks belong under 4.1", scope="4.1")
+evaluation = await case.holdout_eval_and_wait({"baseline": {}, "no memo": {"memo": "none"}})
+print(evaluation.report.summary())
+```
+
+`api.records_case(case_id)` returns the same handle for an existing case without making a request; the first classify call with plain rows reads the dataset's field mapping from the server. `case.get_record(key)` reads one record back, and `case.pending_actions()` returns `AgentAction` objects with `confirm()` and `reject()`. `classify_scores(results, truth, tree=nodes)` scores classify results per tree level against a `{key: code}` mapping as `LevelScore` counts (`1/2 (50%)`); `classify_accuracy` returns the same as fractions.
+
 ## Workbook normalization (v1)
 
 Submit one native `.xlsx` workbook with a nonblank interpretation prompt. Do not provide a target schema. Poll the job, then inspect the returned dataset envelope and its `issues` (a dataset may be `complete` or `needsReview`). Fetch the caller-inspectable transformation plan and source map when you need provenance. The SDK does not start downstream processing automatically; choose the next step in your application.

{docu_devs_api_client-1.11.0 → docu_devs_api_client-1.12.1}/README.md

@@ -15,6 +15,38 @@ Use `propose_contract_analysis_finding_test_case(...)` to turn one captured find
 pip install docu-devs-api-client
 ```
 
+## Case records
+
+Create a records case, load rows, and classify them against a category tree. Long-running calls return a job handle; the `*_and_wait` variants block until the job finishes.
+
+```python
+import os
+
+from docudevs import DocuDevsClient
+
+api = DocuDevsClient(token=os.environ["DOCUDEVS_API_KEY"])
+case = await api.create_records_case(
+    "Product classification",
+    key="ean",
+    text=["name", "generic_name", "ingredients"],
+    label="leaf",
+    metadata=["brand"],
+    target_depth=[1, 2, 3],
+)
+await case.import_records_and_wait(rows)  # dicts keyed by the field names above
+await case.set_tree_and_wait(nodes, name="Taxonomy v1")
+
+job = await case.classify_and_wait(keys=["4001", "4002"], llm_level="MINI")
+for row in await job.flagged():
+    await row.accept()  # or row.correct("4.1.2", reason="...") / row.feedback("...")
+
+await case.memo.add("Oat drinks belong under 4.1", scope="4.1")
+evaluation = await case.holdout_eval_and_wait({"baseline": {}, "no memo": {"memo": "none"}})
+print(evaluation.report.summary())
+```
+
+`api.records_case(case_id)` returns the same handle for an existing case without making a request; the first classify call with plain rows reads the dataset's field mapping from the server. `case.get_record(key)` reads one record back, and `case.pending_actions()` returns `AgentAction` objects with `confirm()` and `reject()`. `classify_scores(results, truth, tree=nodes)` scores classify results per tree level against a `{key: code}` mapping as `LevelScore` counts (`1/2 (50%)`); `classify_accuracy` returns the same as fractions.
+
 ## Workbook normalization (v1)
 
 Submit one native `.xlsx` workbook with a nonblank interpretation prompt. Do not provide a target schema. Poll the job, then inspect the returned dataset envelope and its `issues` (a dataset may be `complete` or `needsReview`). Fetch the caller-inspectable transformation plan and source map when you need provenance. The SDK does not start downstream processing automatically; choose the next step in your application.

docu_devs_api_client-1.12.1/docudevs/__init__.py

@@ -0,0 +1,91 @@
+"""A client library for accessing DocuDevs API"""
+
+from .client import AuthenticatedClient, Client
+from .client_pipeline import ClientPipeline, ClientPipelineError
+from .client_pipeline_runner import ClientPipelineRun
+from .docudevs_client import (
+    DocuDevsClient,
+    File,
+    TemplateFillRequest,
+    UploadCommand,
+    UploadDocumentBody,
+    UploadFilesBody,
+)
+from .pipeline import NodeRef, P, Pipeline, PipelinePath, and_, eq, exists, ne, not_, or_
+from .records_case import (
+    AgentAction,
+    AgentRun,
+    AgentRunFailed,
+    ChosenCategory,
+    ClassifyFailed,
+    ClassifyJob,
+    ClassifyJobFailed,
+    ClassifyRow,
+    DocuDevsJobError,
+    EvalFailed,
+    EvalJob,
+    EvalReport,
+    ImportFailed,
+    ImportJob,
+    LevelScore,
+    MemoEntry,
+    Record,
+    RecordsCase,
+    RecordsImportFailed,
+    TreeActivation,
+    TreeActivationFailed,
+    TreeVersion,
+    classify_accuracy,
+    classify_scores,
+)
+from .schema import array_schema, json_schema
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+    "ClientPipeline",
+    "ClientPipelineError",
+    "ClientPipelineRun",
+    "DocuDevsClient",
+    "UploadDocumentBody",
+    "UploadCommand",
+    "File",
+    "UploadFilesBody",
+    "TemplateFillRequest",
+    "RecordsCase",
+    "ImportJob",
+    "ImportFailed",
+    "RecordsImportFailed",
+    "ClassifyJob",
+    "AgentAction",
+    "ClassifyRow",
+    "LevelScore",
+    "Record",
+    "ChosenCategory",
+    "ClassifyFailed",
+    "ClassifyJobFailed",
+    "EvalJob",
+    "EvalReport",
+    "EvalFailed",
+    "AgentRun",
+    "AgentRunFailed",
+    "MemoEntry",
+    "TreeVersion",
+    "TreeActivation",
+    "TreeActivationFailed",
+    "DocuDevsJobError",
+    "classify_accuracy",
+    "classify_scores",
+    "P",
+    "NodeRef",
+    "Pipeline",
+    "PipelinePath",
+    "and_",
+    "eq",
+    "exists",
+    "ne",
+    "not_",
+    "or_",
+    "array_schema",
+    "json_schema",
+)

{docu_devs_api_client-1.11.0 → docu_devs_api_client-1.12.1}/docudevs/docudevs_client.py

@@ -119,6 +119,7 @@ from .api.operations.submit_operation import (
 from .api.template import delete_template, fill, list_templates, metadata
 from .client import AuthenticatedClient
 from .models import LlmType, OcrCommand, OcrType, UploadCommand, UploadDocumentBody
+from .models.cases_controller_create_case_request import CasesControllerCreateCaseRequest
 from .models.create_embedding_provider_request import CreateEmbeddingProviderRequest
 from .models.create_model_credential_request import CreateModelCredentialRequest
 from .models.extraction_mode import check_extraction_mode
@@ -132,6 +133,14 @@ from .models.tool_descriptor import ToolDescriptor
 from .models.update_embedding_provider_request import UpdateEmbeddingProviderRequest
 from .models.upload_files_body import UploadFilesBody
 from .models.upload_template_body import UploadTemplateBody
+from .records_case import (
+    AgentRunFailed,
+    ClassifyJobFailed,
+    EvalFailed,
+    RecordsCase,
+    RecordsImportFailed,
+)
+from .records_case import create_records_case as build_records_case
 from .types import UNSET, File, Unset
 
 
@@ -156,38 +165,6 @@ class RecordsApiError(Exception):
         super().__init__(f"HTTP {status_code}: {body}")
 
 
-class RecordsImportFailed(Exception):
-    """An import or records job ended in failure."""
-
-    def __init__(self, message: str, details: Any = None):
-        self.details = details
-        super().__init__(message)
-
-
-class ClassifyJobFailed(Exception):
-    """A classify job ended as FAILED or CANCELLED."""
-
-    def __init__(self, message: str, details: Any = None):
-        self.details = details
-        super().__init__(message)
-
-
-class AgentRunFailed(Exception):
-    """A headless agent run ended as FAILED or CANCELLED."""
-
-    def __init__(self, message: str, details: Any = None):
-        self.details = details
-        super().__init__(message)
-
-
-class EvalFailed(Exception):
-    """A holdout evaluation ended as FAILED."""
-
-    def __init__(self, message: str, details: Any = None):
-        self.details = details
-        super().__init__(message)
-
-
 def _records_error_body(response: Any) -> Any:
     try:
         return response.json()
@@ -4188,10 +4165,59 @@ class DocuDevsClient:
             await asyncio.sleep(poll_interval)
 
     # Cases management methods
-    async def create_case(self, body):
-        """Create a new case."""
+    async def create_case(self, body=None, *, name=None, description=None):
+        """Create a new case from a create-case body, or from name= and description=."""
+        if body is None:
+            if name is None:
+                raise ValueError("Give a create-case body or a name")
+            body = CasesControllerCreateCaseRequest(
+                name=name, description=description if description is not None else UNSET
+            )
         return await create_case_async(client=self._client, body=body)
 
+    async def create_case_id(self, name: str, description: Optional[str] = None) -> int:
+        """Create a case and return its id. Raises RecordsApiError when the case is not created."""
+        response = await self.create_case(name=name, description=description)
+        status = int(response.status_code)
+        if status not in (200, 201):
+            raise RecordsApiError(status, _records_error_body(response))
+        parsed_id = getattr(getattr(response, "parsed", None), "id", None)
+        if parsed_id is not None and not isinstance(parsed_id, Unset):
+            return int(parsed_id)
+        return int(json.loads(response.content)["id"])
+
+    async def create_records_case(
+        self,
+        name: str,
+        *,
+        key: str,
+        text: Union[Sequence[str], Mapping[str, str]],
+        label: Optional[str] = None,
+        metadata: Optional[Union[Sequence[str], Mapping[str, str]]] = None,
+        embedded_text: Union[None, str, Mapping[str, Any]] = None,
+        target_depth: Optional[Sequence[int]] = None,
+        index_settings: Optional[Mapping[str, Any]] = None,
+        description: Optional[str] = None,
+    ) -> RecordsCase:
+        """Create a case with a records dataset and return its RecordsCase handle. See
+        records_case.create_records_case for the field and embedded text rules."""
+        return await build_records_case(
+            self,
+            name,
+            key=key,
+            text=text,
+            label=label,
+            metadata=metadata,
+            embedded_text=embedded_text,
+            target_depth=target_depth,
+            index_settings=index_settings,
+            description=description,
+        )
+
+    def records_case(self, case_id: Union[int, str]) -> RecordsCase:
+        """A RecordsCase handle for an existing case. Makes no request."""
+        return RecordsCase(self, case_id)
+
     async def list_cases(self):
         """List all cases."""
         return await list_cases_async(client=self._client)