reducto-cli 0.1.0__py3-none-any.whl

reducto_cli/INSTRUCTIONS.md

@@ -0,0 +1,152 @@
+# Reducto CLI
+
+Welcome to the Reducto CLI. This tool lets you parse documents, extract structured data, and modify documents using Reducto’s platform.
+
+## Usage
+
+- Both commands accept a single file or a directory. Directories are scanned recursively and only supported files (below) are processed.
+
+### Examples
+
+- Parse a single file: `reducto parse path/to/document.pdf`
+- Parse an entire folder: `reducto parse ./docs`
+- Extract with a schema (path or inline JSON): `reducto extract ./docs/invoice.pdf -s schemas/invoice.json`
+
+Parsed outputs are written as `<filename>.parse.md` with YAML front matter. Extraction reuses existing parses when possible and saves `<filename>.extract.json` containing only the payload.
+
+## Supported File Types
+
+  • PDF: `.pdf`  
+  • Images: `.png`, `.jpg`, `.jpeg`  
+  • Office documents: `.doc`, `.docx`, `.ppt`, `.pptx`  
+  • Spreadsheets: `.xls`, `.xlsx`  
+
+Commands accept either a file or a directory. Directories are scanned recursively, and only the supported file types listed above are processed.
+
+## Parse Command Options
+
+The `parse` command supports several flags to customize parsing behavior:
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--agentic` | Enables all agentic options for tables, text, and figures. Increases accuracy but also increases latency. Use when document quality or complex layouts require enhanced processing. |
+| `--change-tracking` | Enables change tracking during parsing. Returns `<s>` tags around strikethrough text, `<u>` tags around underlined text, and `<change>` tags around colored adjacent strikethrough and underlined text. Useful for documents with revision history. |
+| `--highlights` | Include highlighted text in the parsed output. |
+| `--hyperlinks` | Include embedded hyperlinks in the parsed output. |
+| `--comments` | Include document comments in the parsed output. |
+
+### Examples
+
+```bash
+# Basic parse
+reducto parse document.pdf
+
+# Parse with maximum accuracy (slower)
+reducto parse document.pdf --agentic
+
+# Parse a contract with change tracking
+reducto parse contract.pdf --change-tracking
+
+# Parse with all metadata
+reducto parse document.pdf --hyperlinks --comments --highlights
+
+# Combine flags as needed
+reducto parse legal_doc.pdf --agentic --change-tracking --comments
+```
+
+## Extract Command Overview
+
+The `extract` command enables you to pull specific, structured data from your documents according to a schema you provide (using JSON Schema). It is designed to automate information extraction by mapping complex or unstructured documents—such as invoices, receipts, reports, forms, contracts, financial statements, or tables—into machine-readable JSON.
+
+Common use cases include:
+- Extracting line items, totals, vendor/customer info from invoices and receipts
+- Pulling key fields, tables, or sections from contracts or legal documents
+- Capturing form field values from scanned forms or applications
+- Summarizing structured results from reports, statements, or medical records
+
+By providing a schema, you ensure consistency and determinism, so the extracted JSON conforms exactly to your business requirements. This is especially valuable for automating downstream processing pipelines, integrating with databases, or feeding data to other tools.
+
+You can perform extraction on individual files or batches (folders), and extracted payloads are saved as `<filename>.extract.json`.
+
+## Schema Guidelines for `reducto extract`
+
+  • Schemas must be valid JSON Schema documents.  
+  • The top-level schema **must** be an object (`{"type": "object", ...}`) — inline strings or arrays are not permitted.  
+  • Provide explicit property definitions so the extractor can map fields deterministically.  
+  • Schemas may be supplied as file paths or inline JSON strings.
+
+### Example Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "article_number": {"type": "string"},
+          "description": {"type": "string"},
+          "quantity": {"type": "number"},
+          "unit_price": {"type": "number"},
+          "total_price": {"type": "number"}
+        },
+        "required": [
+          "article_number",
+          "description",
+          "quantity",
+          "unit_price",
+          "total_price"
+        ]
+      }
+    }
+  },
+  "required": ["items"]
+}
+```
+
+You can reuse parses across multiple extractions: the CLI automatically detects existing `.parse.md` files, rehydrates the recorded job ID, and uses `jobid://<id>` references to accelerate extraction jobs.
+
+## Editing Documents with `reducto edit`
+
+The `edit` command allows you to modify documents using natural language instructions. It uploads the document, applies the specified edits, and downloads the resulting file.
+
+### Usage
+
+```bash
+reducto edit path/to/document.pdf --instructions "Your editing instructions here"
+reducto edit path/to/document.pdf -i "Your editing instructions here"
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes | Path to a file or directory. Directories are scanned recursively for supported file types. |
+| `--instructions`, `-i` | Yes | Natural language instructions describing the edits to apply. |
+
+### Output
+
+Edited files are saved alongside the original with the naming pattern `<filename>.edited.<extension>`. For example:
+- `invoice.pdf` → `invoice.edited.pdf`
+- `report.docx` → `report.edited.docx`
+
+### Examples
+
+```bash
+reducto edit contract.pdf -i "Fill in the client name as 'Acme Corporation' and set the contract date to January 15, 2024"
+
+reducto edit document.pdf -i "Fill out the form with: Name: John Doe, Email: john@example.com, Select 'Yes' for newsletter subscription"
+```
+
+### Effective Instructions
+
+For best results with the `--instructions` flag:
+- Be specific about what content to modify and how
+- Reference specific elements (headers, footers, tables, specific text)
+- Describe the desired outcome clearly
+- For bulk operations on directories, ensure instructions apply uniformly to all file types
+

reducto_cli/__init__.py

@@ -0,0 +1,10 @@
+"""Utilities for the reducto CLI."""
+
+__all__ = [
+    "config",
+    "files",
+    "parser",
+    "extractor",
+    "schema",
+    "help_text",
+]

reducto_cli/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

reducto_cli/auth.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import os
+import platform
+import time
+import webbrowser
+import asyncio
+
+import httpx
+import typer
+from .config import _write_api_key, _read_saved_api_key
+
+
+class AuthSpinner:
+    """Simple loading spinner for authentication polling."""
+
+    def __init__(self):
+        self._spinner_chars = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+        self._running = False
+        self._task = None
+
+    async def start(self, message: str = "Waiting for authentication"):
+        """Start the spinner."""
+        self._running = True
+        self._task = asyncio.create_task(self._spin(message))
+
+    async def stop(self):
+        """Stop the spinner."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+
+    async def _spin(self, message: str):
+        """Spinner animation loop."""
+        i = 0
+        while self._running:
+            char = self._spinner_chars[i % len(self._spinner_chars)]
+            print(f"\r{char} {message}...", end="", flush=True)
+            i += 1
+            await asyncio.sleep(0.1)
+        print("\r" + " " * (len(message) + 10), end="", flush=True)  # Clear line
+
+
+async def authenticate_with_device_code() -> None:
+    """Authenticate with Reducto via device code flow."""
+
+    # Check if API key already exists
+    existing_key = _read_saved_api_key()
+    if existing_key:
+        if not typer.confirm("An API key is already set. Do you want to replace it?"):
+            typer.echo("Authentication cancelled.")
+            return
+
+    client_info = {
+        "hostname": platform.node(),
+        "os": f"{platform.system()} {platform.release()}",
+        "cli_version": "1.0.0",
+    }
+
+    async with httpx.AsyncClient() as client:
+        studio_api_url = os.getenv(
+            "REDUCTO_STUDIO_API_URL",
+            "https://mild-moose-423.convex.site",
+        )
+
+        try:
+            # Request device code
+            response = await client.post(
+                f"{studio_api_url}/deviceAuth/deviceCode",
+                json={"clientInfo": client_info},
+                timeout=10.0,
+            )
+            response.raise_for_status()
+            auth_data = response.json()
+
+            device_code = auth_data["device_code"]
+            user_code = auth_data["user_code"]
+            verification_uri = auth_data["verification_uri_complete"]
+            interval = auth_data["interval"]
+            expires_in = auth_data["expires_in"]
+
+            # Show instructions to user
+            typer.echo("\nReducto CLI Authentication")
+            typer.echo(f"Your code: {typer.style(user_code, fg='cyan', bold=True)}")
+            typer.echo(f"Visit: {typer.style(verification_uri, fg='blue')}")
+            typer.echo(f"Code expires in {expires_in} seconds")
+
+            # Try to open browser automatically
+            try:
+                webbrowser.open(verification_uri)
+                typer.echo("Browser opened automatically.", err=True)
+            except Exception:
+                typer.echo("Could not open browser automatically.", err=True)
+
+            # Start spinner and poll for approval
+            spinner = AuthSpinner()
+            await spinner.start()
+
+            start_time = time.time()
+            try:
+                while time.time() - start_time < expires_in:
+                    await asyncio.sleep(interval)
+
+                    try:
+                        poll_response = await client.post(
+                            f"{studio_api_url}/deviceAuth/poll",
+                            json={"device_code": device_code},
+                            timeout=10.0,
+                        )
+                        poll_response.raise_for_status()
+                        poll_data = poll_response.json()
+
+                        if poll_data["status"] == "approved":
+                            api_key = poll_data["api_key"]
+                            _write_api_key(api_key)
+                            await spinner.stop()
+                            typer.echo(
+                                f"{typer.style('✓ Authentication successful!', fg='green', bold=True)}"
+                            )
+                            typer.echo("API key saved to ~/.reducto/config.yaml")
+                            return
+
+                        elif poll_data["status"] == "denied":
+                            await spinner.stop()
+                            typer.echo(
+                                f"{typer.style('✗ Authentication denied.', fg='red', bold=True)}"
+                            )
+                            raise typer.Exit(1)
+
+                        elif poll_data["status"] == "expired":
+                            await spinner.stop()
+                            typer.echo(
+                                f"{typer.style('✗ Authentication expired.', fg='red', bold=True)}"
+                            )
+                            typer.echo("Please try again.")
+                            raise typer.Exit(1)
+
+                        # Still pending, continue polling
+
+                    except httpx.HTTPStatusError as e:
+                        if e.response.status_code == 400:
+                            error_data = e.response.json()
+                            if error_data.get("error") == "slow_down":
+                                await asyncio.sleep(interval)
+                                continue
+                        await spinner.stop()
+                        typer.echo(f"{typer.style('✗ Polling failed:', fg='red')} {e}")
+                        raise typer.Exit(1)
+
+                # If we get here, the session expired
+                await spinner.stop()
+                typer.echo(
+                    f"{typer.style('✗ Authentication timed out.', fg='red', bold=True)}"
+                )
+                typer.echo("Please try again.")
+                raise typer.Exit(1)
+
+            except Exception:
+                await spinner.stop()
+                raise
+
+        except httpx.HTTPStatusError as e:
+            typer.echo(f"{typer.style('✗ Authentication failed:', fg='red')} {e}")
+            if e.response.status_code == 500:
+                typer.echo("Server error. Please try again later.")
+            raise typer.Exit(1)
+        except Exception as e:
+            typer.echo(f"{typer.style('✗ Authentication failed:', fg='red')} {e}")
+            raise typer.Exit(1)

reducto_cli/cli.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from async_typer import AsyncTyper, Option
+from reducto import AsyncReducto
+
+from .config import get_api_key
+from .extractor import extract_files
+from .editor import edit_files
+from .files import collect_files
+from .help_text import load_help_text
+from .parser import parse_files
+from .schema import load_schema
+from .auth import authenticate_with_device_code
+
+
+app = AsyncTyper(help=load_help_text())
+
+
+@app.async_command()
+async def login() -> None:
+    """Authenticate with Reducto via device code flow."""
+    await authenticate_with_device_code()
+
+
+@app.async_command()
+async def parse(
+    path: Path,
+    agentic: bool = Option(False, "--agentic", help="Enables all agentic options. Increases latency and accuracy"),
+    change_tracking: bool = Option(False, "--change-tracking", help="Enables change tracking during parsing. Returns <s> tags around strikethrough text, <u> tags around underlined text, and <change> tags around colored adjacent strikethough and underlined text"),
+    highlights: bool = Option(False, "--highlights", help="Highlight text in the parsed document"),
+    hyperlinks: bool = Option(False, "--hyperlinks", help="Include embedded hyperlinks"),
+    comments: bool = Option(False, "--comments", help="Include comments"),
+) -> None:
+    files = collect_files(path)
+    if not files:
+        typer.echo("No files found to parse.", err=True)
+        raise typer.Exit(1)
+
+    include = [
+        option for flag, option in [
+            (change_tracking, "change_tracking"),
+            (highlights, "highlight"),
+            (hyperlinks, "hyperlinks"),
+            (comments, "comments"),
+        ] if flag
+    ]
+
+    api_key = get_api_key()
+    async with AsyncReducto(api_key=api_key) as client:
+        await parse_files(client, files, agentic, include)
+
+
+@app.async_command()
+async def extract(path: Path, schema: str = Option(..., "--schema", "-s")) -> None:
+    files = collect_files(path)
+    if not files:
+        typer.echo("No files found to extract.", err=True)
+        raise typer.Exit(1)
+
+    schema_value = load_schema(schema)
+    api_key = get_api_key()
+    async with AsyncReducto(api_key=api_key) as client:
+        await extract_files(client, files, schema_value)
+
+
+@app.async_command()
+async def edit(path: Path, instructions: str = Option(..., "--instructions", "-i")) -> None:
+    files = collect_files(path)
+    if not files:
+        typer.echo("No files found to edit.", err=True)
+        raise typer.Exit(1)
+
+    api_key = get_api_key()
+    async with AsyncReducto(api_key=api_key) as client:
+        await edit_files(client, files, instructions)
+
+def main() -> None:
+    app()

reducto_cli/config.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+
+
+CONFIG_PATH = Path.home() / ".reducto" / "config.yaml"
+
+
+def _read_saved_api_key() -> str | None:
+    try:
+        content = CONFIG_PATH.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return None
+
+    for line in content.splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        if key.strip().lower() == "api_key":
+            return value.strip().strip("\"'")
+    return None
+
+
+def _write_api_key(value: str) -> None:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(f"api_key: {value.strip()}\n", encoding="utf-8")
+    try:
+        os.chmod(CONFIG_PATH, 0o600)
+    except OSError:
+        pass
+
+
+def get_api_key() -> str:
+    env_value = os.getenv("REDUCTO_API_KEY")
+    if env_value:
+        return env_value.strip()
+
+    saved_value = _read_saved_api_key()
+    if saved_value:
+        os.environ["REDUCTO_API_KEY"] = saved_value
+        return saved_value
+
+    # Suggest running login command first
+    typer.echo("\nNo API key found. You can authenticate by running:")
+    typer.echo("  " + typer.style("reducto login", fg="cyan", bold=True))
+    typer.echo("\nThis will open a browser to authenticate your CLI.")
+
+    # Still allow manual entry as fallback
+    if typer.confirm("\nOr enter an API key manually?"):
+        entered_value = typer.prompt(
+            "Enter your Reducto API key", hide_input=True
+        ).strip()
+        if not entered_value:
+            typer.echo("An API key is required to continue.", err=True)
+            raise typer.Exit(1)
+
+        _write_api_key(entered_value)
+        os.environ["REDUCTO_API_KEY"] = entered_value
+        return entered_value
+    else:
+        typer.echo("\nPlease run 'reducto login' to authenticate.", err=True)
+        raise typer.Exit(1)

reducto_cli/editor.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterable
+from pathlib import Path
+
+import httpx
+import typer
+from reducto import AsyncReducto, ReductoError
+
+from .files import edit_output_path
+
+
+async def edit_files(client: AsyncReducto, files: Iterable[Path], instructions: str) -> None:
+    tasks = [asyncio.create_task(edit_file(client, file_path, instructions)) for file_path in files]
+    for task in asyncio.as_completed(tasks):
+        destination = await task
+        if destination is not None:
+            typer.echo(f"Saved {destination}")
+
+
+async def edit_file(client: AsyncReducto, file_path: Path, instructions: str) -> Path | None:
+    try:
+        upload = await client.upload(file=file_path)
+    except ReductoError as exc:
+        typer.echo(f"Failed to upload {file_path}: {exc}", err=True)
+        return None
+
+    try:
+        response = await client.edit.run(
+            document_url=upload.file_id,
+            edit_instructions=instructions,
+        )
+    except ReductoError as exc:
+        typer.echo(f"Failed to edit {file_path}: {exc}", err=True)
+        return None
+
+    document_url = getattr(response, "document_url", None)
+    if not document_url:
+        typer.echo(f"No document URL in response for {file_path}", err=True)
+        return None
+
+    destination = edit_output_path(file_path)
+    try:
+        await _download_file(document_url, destination)
+    except Exception as exc:
+        typer.echo(f"Failed to download edited document for {file_path}: {exc}", err=True)
+        return None
+
+    return destination
+
+
+async def _download_file(url: str, destination: Path) -> None:
+    async with httpx.AsyncClient() as http_client:
+        async with http_client.stream("GET", url) as response:
+            response.raise_for_status()
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            with destination.open("wb") as f:
+                async for chunk in response.aiter_bytes():
+                    f.write(chunk)

reducto_cli/extractor.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any, Iterable
+
+import typer
+from reducto import AsyncReducto, ReductoError
+
+from .files import extract_output_path, parse_output_path
+from .parser import ParseInfo, parse_file, read_parse_metadata
+
+
+async def extract_files(client: AsyncReducto, files: Iterable[Path], schema: object) -> None:
+    tasks = [asyncio.create_task(_extract_file(client, file_path, schema)) for file_path in files]
+    for task in asyncio.as_completed(tasks):
+        destination = await task
+        if destination is not None:
+            typer.echo(f"Saved {destination}")
+
+
+async def _extract_file(client: AsyncReducto, file_path: Path, schema: object) -> Path | None:
+    job_id = _existing_job_id(file_path)
+    parse_info: ParseInfo | None = None
+
+    if job_id is None:
+        parse_info = await parse_file(client, file_path)
+        if parse_info is None:
+            return None
+        job_id = parse_info.job_id
+
+    input_payload: object
+    if job_id and job_id != "unknown":
+        input_payload = f"jobid://{job_id}"
+    else:
+        try:
+            upload = await client.upload(file=file_path)
+        except ReductoError as exc:
+            typer.echo(f"Failed to upload {file_path}: {exc}", err=True)
+            return None
+        input_payload = {"file_id": upload.file_id}
+
+    try:
+        response = await client.extract.run(
+            input=input_payload,
+            instructions={"schema": schema},
+        )
+    except ReductoError as exc:
+        typer.echo(f"Failed to extract {file_path}: {exc}", err=True)
+        return None
+
+    content = _response_to_text(response)
+
+    destination = extract_output_path(file_path)
+    destination.write_text(json.dumps(content, indent=2, ensure_ascii=False), encoding="utf-8")
+    return destination
+
+
+def _existing_job_id(source: Path) -> str | None:
+    metadata = read_parse_metadata(source)
+    job_id = metadata.get("job_id")
+    return job_id if job_id else None
+def _response_to_text(response: object) -> Any:
+    if hasattr(response, "model_dump"):
+        data = response.model_dump()
+        cleaned = _strip_metadata(data)
+        return _unwrap_single_result(cleaned)
+    return response
+
+
+def _strip_metadata(data: Any) -> Any:
+    if isinstance(data, dict):
+        return {
+            key: _strip_metadata(value)
+            for key, value in data.items()
+            if key not in {"usage", "job_id", "studio_link", "citations"}
+        }
+    if isinstance(data, list):
+        return [_strip_metadata(item) for item in data]
+    return data
+
+
+def _unwrap_single_result(data: Any) -> Any:
+    if isinstance(data, dict) and "result" in data and len(data) == 1:
+        return _unwrap_single_result(data["result"])
+    if isinstance(data, list) and len(data) == 1:
+        return _unwrap_single_result(data[0])
+    return data

reducto_cli/files.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+import typer
+
+
+PARSE_SUFFIX = ".parse.md"
+EXTRACT_SUFFIX = ".extract.json"
+EDIT_SUFFIX = ".edited"
+GENERATED_SUFFIXES = (PARSE_SUFFIX, EXTRACT_SUFFIX)
+SUPPORTED_EXTENSIONS = {".pdf", ".png", ".jpg", ".jpeg", ".doc", ".docx", ".ppt", ".pptx", ".xls", ".xlsx"}
+
+
+def collect_files(target: Path) -> list[Path]:
+    path = target.expanduser()
+    if not path.exists():
+        raise typer.BadParameter(f"{path} does not exist")
+
+    if path.is_file():
+        return [path] if _should_process(path) else []
+
+    return sorted(p for p in _iter_files(path) if _should_process(p))
+
+
+def _iter_files(directory: Path) -> Iterable[Path]:
+    for item in directory.rglob("*"):
+        if item.is_file():
+            yield item
+
+
+def is_generated(path: Path) -> bool:
+    return any(path.name.endswith(suffix) for suffix in GENERATED_SUFFIXES)
+
+
+def _should_process(path: Path) -> bool:
+    if is_generated(path):
+        return False
+    return path.suffix.lower() in SUPPORTED_EXTENSIONS
+
+
+def parse_output_path(source: Path) -> Path:
+    return source.with_name(f"{source.name}{PARSE_SUFFIX}")
+
+
+def extract_output_path(source: Path) -> Path:
+    return source.with_name(f"{source.name}{EXTRACT_SUFFIX}")
+
+
+def edit_output_path(source: Path) -> Path:
+    return source.with_name(f"{source.stem}{EDIT_SUFFIX}{source.suffix}")

reducto_cli/help_text.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+
+def load_help_text() -> str:
+    try:
+        package_path = resources.files("reducto_cli").joinpath("INSTRUCTIONS.md")
+        content = package_path.read_text(encoding="utf-8").strip()
+        if content:
+            return content
+    except (FileNotFoundError, OSError, AttributeError):
+        pass
+
+    fallback_path = Path(__file__).resolve().parent / "INSTRUCTIONS.md"
+    try:
+        content = fallback_path.read_text(encoding="utf-8").strip()
+        if content:
+            return content
+    except OSError:
+        pass
+
+    return "Reducto CLI"

reducto_cli/parser.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Optional
+
+import typer
+from reducto import AsyncReducto, ReductoError
+from reducto.types.shared.parse_response import ResultFullResult
+
+from .files import parse_output_path
+
+
+@dataclass
+class ParseInfo:
+    job_id: str
+    duration: Optional[float]
+    output_path: Path
+
+
+async def parse_files(client: AsyncReducto, files: Iterable[Path], agentic: bool, formatting_include: list[str]) -> None:
+    tasks = [asyncio.create_task(parse_file(client, file_path, agentic, formatting_include)) for file_path in files]
+    for task in asyncio.as_completed(tasks):
+        info = await task
+        if info is not None:
+            typer.echo(f"Saved {info.output_path}")
+
+
+async def parse_file(client: AsyncReducto, file_path: Path, agentic: bool, formatting_include: list[str]) -> ParseInfo | None:
+    try:
+        upload = await client.upload(file=file_path)
+        kwargs = {"input": {"file_id": upload.file_id}, "formatting": {"include": formatting_include}}
+        if agentic:
+            kwargs["enhance"] = {"agentic": [{"scope": "table"}, {"scope": "text"}, {"scope": "figure"}]}
+        response = await client.parse.run(**kwargs)
+    except ReductoError as exc:
+        typer.echo(f"Failed to parse {file_path}: {exc}", err=True)
+        return None
+
+    text = _extract_text(response.result) if hasattr(response, "result") else None
+    if text is None:
+        typer.echo(f"No textual content available for {file_path}", err=True)
+        return None
+
+    job_id = getattr(response, "job_id", "unknown") or "unknown"
+    duration = getattr(response, "duration", None)
+    front_matter = [
+        "---",
+        f"job_id: {job_id}",
+        f"duration: {duration if duration is not None else 'null'}",
+        "---",
+        "",
+    ]
+
+    destination = parse_output_path(file_path)
+    destination.write_text("\n".join(front_matter + [text]), encoding="utf-8")
+    return ParseInfo(job_id=job_id, duration=duration, output_path=destination)
+
+
+def _extract_text(result: object) -> Optional[str]:
+    if isinstance(result, ResultFullResult) and result.chunks:
+        return result.chunks[0].content
+    return None
+
+
+def read_parse_metadata(source: Path) -> dict[str, str]:
+    path = parse_output_path(source)
+    if not path.exists():
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+
+    data: dict[str, str] = {}
+    for line in lines[1:]:
+        stripped = line.strip()
+        if stripped == "---":
+            break
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        data[key.strip()] = value.strip()
+    return data

reducto_cli/schema.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+
+def load_schema(value: str) -> object:
+    candidate = Path(value).expanduser()
+    if candidate.exists():
+        try:
+            raw = candidate.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise typer.BadParameter(f"Unable to read schema file: {exc}") from exc
+    else:
+        raw = value
+
+    raw = raw.strip()
+    if not raw:
+        raise typer.BadParameter("Schema cannot be empty")
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return raw

reducto_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: reducto-cli
+Version: 0.1.0
+Summary: CLI for Reducto document processing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: async-typer>=0.1.10
+Requires-Dist: reductoai>=0.13.0
+Requires-Dist: typer>=0.20.0
+
+# Reducto CLI
+
+Welcome to the Reducto CLI. This tool lets you parse documents, extract structured data, and modify documents using Reducto’s platform.
+
+## Installation
+
+Install the Reducto CLI using pip:
+
+```bash
+pip install reducto-cli
+```
+
+## Authentication
+
+Before using the CLI, authenticate with your Reducto API key:
+
+```bash
+reducto login
+```
+
+### Examples
+
+- Parse a single file: `reducto parse path/to/document.pdf`
+- Parse an entire folder: `reducto parse ./docs`
+- Extract with a schema (path or inline JSON): `reducto extract ./docs/invoice.pdf -s schemas/invoice.json`
+- Edit a single file: `reducto edit path/to/document.pdf --instructions "Your editing instructions here"`
+
+Parsed outputs are written as `<filename>.parse.md`. Extraction reuses existing parses when possible and saves `<filename>.extract.json` containing only the payload.
+
+## Supported File Types
+
+  • PDF: `.pdf`  
+  • Images: `.png`, `.jpg`, `.jpeg`  
+  • Office documents: `.doc`, `.docx`, `.ppt`, `.pptx`  
+  • Spreadsheets: `.xls`, `.xlsx`  
+
+Commands accept either a file or a directory. Directories are scanned recursively, and only the supported file types listed above are processed.
+
+## Parse Command Options
+
+The `parse` command supports several flags to customize parsing behavior:
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--agentic` | Enables all agentic options for tables, text, and figures. Increases accuracy but also increases latency. Use when document quality or complex layouts require enhanced processing. |
+| `--change-tracking` | Enables change tracking during parsing. Returns `<s>` tags around strikethrough text, `<u>` tags around underlined text, and `<change>` tags around colored adjacent strikethrough and underlined text. Useful for documents with revision history. |
+| `--highlights` | Include highlighted text in the parsed output. |
+| `--hyperlinks` | Include embedded hyperlinks in the parsed output. |
+| `--comments` | Include document comments in the parsed output. |
+
+### Examples
+
+```bash
+# Basic parse
+reducto parse document.pdf
+
+# Parse with maximum accuracy (slower)
+reducto parse document.pdf --agentic
+
+# Parse a contract with change tracking
+reducto parse contract.pdf --change-tracking
+
+# Parse with all metadata
+reducto parse document.pdf --hyperlinks --comments --highlights
+
+# Combine flags as needed
+reducto parse legal_doc.pdf --agentic --change-tracking --comments
+```
+
+## Extract Command Overview
+
+The `extract` command enables you to pull specific, structured data from your documents according to a schema you provide (using JSON Schema). It is designed to automate information extraction by mapping complex or unstructured documents—such as invoices, receipts, reports, forms, contracts, financial statements, or tables—into machine-readable JSON.
+
+Common use cases include:
+- Extracting line items, totals, vendor/customer info from invoices and receipts
+- Pulling key fields, tables, or sections from contracts or legal documents
+- Capturing form field values from scanned forms or applications
+- Summarizing structured results from reports, statements, or medical records
+
+By providing a schema, you ensure consistency and determinism, so the extracted JSON conforms exactly to your business requirements. This is especially valuable for automating downstream processing pipelines, integrating with databases, or feeding data to other tools.
+
+You can perform extraction on individual files or batches (folders), and extracted payloads are saved as `<filename>.extract.json`.
+
+## Schema Guidelines for `reducto extract`
+
+  • Schemas must be valid JSON Schema documents.  
+  • The top-level schema **must** be an object (`{"type": "object", ...}`) — inline strings or arrays are not permitted.  
+  • Provide explicit property definitions so the extractor can map fields deterministically.  
+  • Schemas may be supplied as file paths or inline JSON strings.
+
+### Example Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "article_number": {"type": "string"},
+          "description": {"type": "string"},
+          "quantity": {"type": "number"},
+          "unit_price": {"type": "number"},
+          "total_price": {"type": "number"}
+        },
+        "required": [
+          "article_number",
+          "description",
+          "quantity",
+          "unit_price",
+          "total_price"
+        ]
+      }
+    }
+  },
+  "required": ["items"]
+}
+```
+
+You can reuse parses across multiple extractions: the CLI automatically detects existing `.parse.md` files, rehydrates the recorded job ID, and uses `jobid://<id>` references to accelerate extraction jobs.
+
+## Editing Documents with `reducto edit`
+
+The `edit` command allows you to modify documents using natural language instructions. It uploads the document, applies the specified edits, and downloads the resulting file.
+
+### Usage
+
+```bash
+reducto edit path/to/document.pdf --instructions "Your editing instructions here"
+reducto edit path/to/document.pdf -i "Your editing instructions here"
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes | Path to a file or directory. Directories are scanned recursively for supported file types. |
+| `--instructions`, `-i` | Yes | Natural language instructions describing the edits to apply. |
+
+### Output
+
+Edited files are saved alongside the original with the naming pattern `<filename>.edited.<extension>`. For example:
+- `invoice.pdf` → `invoice.edited.pdf`
+- `report.docx` → `report.edited.docx`
+
+### Examples
+
+```bash
+reducto edit contract.pdf -i "Fill in the client name as 'Acme Corporation' and set the contract date to January 15, 2024"
+
+reducto edit document.pdf -i "Fill out the form with: Name: John Doe, Email: john@example.com, Select 'Yes' for newsletter subscription"
+```
+
+### Effective Instructions
+
+For best results with the `--instructions` flag:
+- Be specific about what content to modify and how
+- Reference specific elements (headers, footers, tables, specific text)
+- Describe the desired outcome clearly
+- For bulk operations on directories, ensure instructions apply uniformly to all file types
+

reducto_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+reducto_cli/INSTRUCTIONS.md,sha256=GqtwwxmdHJrSLiZtv7FbLZgsH4zqTVf4eBFBAlRIrzI,6154
+reducto_cli/__init__.py,sha256=_5mutx4EYCl4_jqZovpr8yIPn1BdTC-dwT9WfRvLRJM,141
+reducto_cli/__main__.py,sha256=wu5N2wk8mvBgyvr2ghmQf4prezAe0_i-p123VVreyYc,62
+reducto_cli/auth.py,sha256=cTVN7swoh9YacM1gt_0eNJqNUJvN8B-puECUpBNGKWg,6542
+reducto_cli/cli.py,sha256=YX6FL_egqFNY3wiZkmKJiN4ZIOt0WyB_I2z39iP43CA,2706
+reducto_cli/config.py,sha256=lZL5kz9cACLNfO6vdSohJegNyHGDqfW-ea5UuYK4JZA,1942
+reducto_cli/editor.py,sha256=-Pf0eynMatWhii8OFzrcROFAHAMCk99LX5iEdMvTZq0,2010
+reducto_cli/extractor.py,sha256=fO2zSJ9ecLsTk-VFkdTes0jFCAPOs_i6lVKCnmlrcrM,2903
+reducto_cli/files.py,sha256=DAz9WUBV_YoyelLQS-k8Dowyr99tZVtOkadS4FB5I70,1406
+reducto_cli/help_text.py,sha256=80uhM6NzgGdbuxgEv4Lx2XMe6b3I82l0hE-CgHqMWe0,655
+reducto_cli/parser.py,sha256=it2LO7RznuVJ0TvVey9VcUIGjhfJVPkHl8-g__YqwrI,2878
+reducto_cli/schema.py,sha256=Ttcx3IcyKVDrnJGmLxGeJhGH1QdIsvr-csnpwmDaxzA,601
+reducto_cli-0.1.0.dist-info/METADATA,sha256=_ICs2adq_SnTvj8jW_b_GRs00HLzDk1_Auengwg-3Jc,6550
+reducto_cli-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+reducto_cli-0.1.0.dist-info/entry_points.txt,sha256=dRLbGtD1LhU-eGfITuetnpvq6q-_ELrXJy4zzRnWz0w,48
+reducto_cli-0.1.0.dist-info/top_level.txt,sha256=PkGOBDvo-HEUItp3EV_P0PMXKLudo6CJEtB9oofR_wE,12
+reducto_cli-0.1.0.dist-info/RECORD,,

reducto_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

reducto_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+reducto = reducto_cli.cli:app

reducto_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+reducto_cli