Skip to content

Commit bc76ba5

Browse files
datalogics-kamdatalogics-kam
committed
docs: Add badges and LLM-specific guides to documentation
- Added `llms.txt` and `llms-full.txt` as new machine-readable guides for LLMs and automated tools requiring SDK insights. - Included a badge in `README.md` linking to `llms.txt`. - Enhanced documentation accessibility for AI-driven workflows and code-assistant integrations. Assisted-by: Codex
1 parent 7f9fed4 commit bc76ba5

3 files changed

Lines changed: 293 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
[![Tests](https://img.shields.io/github/actions/workflow/status/pdfrest/pdfrest-python/test-and-publish.yml?branch=main&label=tests)](https://github.com/pdfrest/pdfrest-python/actions/workflows/test-and-publish.yml)
44
[![Python Versions](https://img.shields.io/pypi/pyversions/pdfrest)](https://pypi.org/project/pdfrest/)
5+
[![llms.txt](https://img.shields.io/badge/llms.txt-available-2ea44f)](https://python.pdfrest.com/llms.txt)
56

67
Build production-grade PDF automation with the official Python SDK for
78
[pdfRest](https://pdfrest.com/): a powerful PDF API platform for conversion,

‎docs/llms-full.txt‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
# pdfRest Python SDK Documentation (Full LLM Guide)
2+
3+
> Expanded machine-readable guide for the `pdfrest` Python SDK documentation,
4+
> examples, and repository resources.
5+
6+
This file is intended for LLMs, assistants, and automated documentation tools
7+
that need a richer overview than `llms.txt`. It summarizes the purpose of the
8+
SDK, the most important docs pages, common usage patterns, and practical
9+
integration constraints.
10+
11+
The `pdfrest` Python SDK is the official Python client for the pdfRest PDF API.
12+
It provides typed request/response models, synchronous and asynchronous clients,
13+
and high-level endpoint helpers for common PDF workflows such as conversion,
14+
OCR, extraction, redaction, security, forms, and document optimization.
15+
16+
## Canonical Entry Points
17+
18+
- [Short Guide (`llms.txt`)](https://python.pdfrest.com/llms.txt): Minimal,
19+
curated index of the most important docs and platform links.
20+
- [SDK Docs Home](https://python.pdfrest.com/): Landing page for the Python SDK
21+
documentation.
22+
- [GitHub Repository](https://github.com/pdfrest/pdfrest-python): Source code,
23+
tests, examples, CI workflows, and contribution guidance.
24+
- [PyPI Package](https://pypi.org/project/pdfrest/): Install metadata and
25+
release history.
26+
27+
## Product and Platform Context
28+
29+
- [pdfRest Homepage](https://pdfrest.com/): Product overview and capabilities.
30+
- [pdfRest API Docs](https://pdfrest.com/apidocs/): Endpoint-level REST
31+
documentation for the platform itself.
32+
- [API Lab](https://pdfrest.com/apilab/): Interactive API testing and starter
33+
code generation.
34+
- [Product Documentation](https://docs.pdfrest.com/): Broader deployment and
35+
platform guidance (Cloud, AWS, Container, and feature docs).
36+
37+
Use the Python SDK docs for Python integration details. Use the platform API
38+
docs/product docs when you need endpoint semantics, deployment decisions, or
39+
service-wide behavior outside the Python wrapper.
40+
41+
## Core SDK Concepts
42+
43+
- Sync and async clients:
44+
- `PdfRestClient` for synchronous workflows.
45+
- `AsyncPdfRestClient` for asynchronous workflows.
46+
- File-first workflow:
47+
- Upload local files first (for example via `client.files.create_from_paths`).
48+
- Pass uploaded `PdfRestFile` objects into endpoint helpers.
49+
- Download/read/stream outputs via file helpers.
50+
- Authentication:
51+
- Default environment variable is `PDFREST_API_KEY`.
52+
- The SDK uses the `Api-Key` header for pdfRest-hosted endpoints.
53+
- Deployment targeting:
54+
- Cloud uses the default base URL.
55+
- Self-hosted deployments can be targeted with `base_url=...` while keeping
56+
the same Python method calls.
57+
- Typed interfaces:
58+
- Pydantic-backed models validate inputs and expose structured responses.
59+
- Public shared type contracts are available under `pdfrest.types`.
60+
61+
## Documentation Pages (Python SDK)
62+
63+
### Getting Started
64+
65+
- [Getting Started](https://python.pdfrest.com/getting-started/)
66+
- Purpose: First-time setup and initial API call.
67+
- Includes:
68+
- install instructions (`uv`, `pip`, `poetry`)
69+
- exporting `PDFREST_API_KEY`
70+
- upload + extract-text quickstart example
71+
- links to API reference and API Lab
72+
73+
### Client Configuration
74+
75+
- [Client Configuration](https://python.pdfrest.com/client-configuration/)
76+
- Purpose: Configure runtime behavior and request customization.
77+
- Typical topics:
78+
- API key and base URL
79+
- timeouts
80+
- extra headers / query / body overrides
81+
- transport behavior and request options
82+
- logging/debugging
83+
84+
### Using Files
85+
86+
- [Using Files](https://python.pdfrest.com/using-files/)
87+
- Purpose: Explain the SDK file-management model used by most endpoint helpers.
88+
- Key workflows:
89+
- upload from paths/URLs
90+
- read bytes/text/json from results
91+
- write downloaded files locally
92+
- stream file content
93+
- delete remote files
94+
95+
### API Guide
96+
97+
- [API Guide](https://python.pdfrest.com/api-guide/)
98+
- Purpose: Practical SDK usage guidance across endpoint families.
99+
- Use this when you want examples and integration patterns rather than raw API
100+
signatures.
101+
102+
### API Reference
103+
104+
- [API Reference](https://python.pdfrest.com/api-reference/)
105+
- Purpose: Generated reference for:
106+
- `pdfrest` package exports
107+
- public types (`pdfrest.types`)
108+
- public models (`pdfrest.models`)
109+
- Use this for precise names, signatures, and import surfaces.
110+
111+
## Common Workflow Patterns
112+
113+
### Upload then process
114+
115+
Most document-processing calls follow this pattern:
116+
117+
1. Upload source files.
118+
2. Pass returned `PdfRestFile` objects into a client method.
119+
3. Use the response to inspect metadata and/or download resulting files.
120+
121+
This file-based flow is central to the SDK and is preferred over passing raw
122+
file IDs directly in application code.
123+
124+
### Sync usage pattern
125+
126+
- Use `with PdfRestClient() as client:`
127+
- This ensures the underlying HTTP transport is closed deterministically.
128+
129+
### Async usage pattern
130+
131+
- Use `async with AsyncPdfRestClient() as client:`
132+
- This ensures async transport cleanup and avoids leaked connections.
133+
134+
### Request customization
135+
136+
Many endpoint helpers support runtime overrides for advanced integration cases:
137+
138+
- `extra_headers`
139+
- `extra_query`
140+
- `extra_body`
141+
- `timeout`
142+
143+
Use these when you need to test server behavior, pass preview features, or
144+
adjust request behavior without bypassing the typed SDK entirely.
145+
146+
## Endpoint Families (High-Level)
147+
148+
This SDK includes high-level helpers across major pdfRest capabilities. Refer
149+
to the API guide and API reference for exact method names and options.
150+
151+
### Conversion and Export
152+
153+
- Convert to Office/image/Markdown formats (for example Word, Excel,
154+
PowerPoint, PNG/JPEG/TIFF/GIF/BMP, Markdown)
155+
- Convert source assets to PDF (Office, HTML, URL, email, images, PostScript)
156+
- Convert to standards formats (`PDF/A`, `PDF/X`)
157+
158+
### Extraction and Analysis
159+
160+
- Extract PDF text
161+
- Extract text to file outputs
162+
- Extract images
163+
- Query PDF information/metadata
164+
- OCR PDF
165+
166+
### AI and Language Workflows
167+
168+
- Summarize PDF text
169+
- Translate PDF text
170+
- Translate/summarize outputs to files (where supported)
171+
- Markdown conversion for downstream indexing, retrieval, and LLM pipelines
172+
173+
### Security and Governance
174+
175+
- Redaction preview/apply
176+
- Passwords and permissions
177+
- Encryption/decryption/restrictions
178+
- Watermarking (text/image)
179+
- Digital signing
180+
181+
### Document Composition and Optimization
182+
183+
- Merge PDFs
184+
- Split PDFs
185+
- Compress
186+
- Linearize
187+
- Rasterize
188+
- Flatten annotations/layers/transparencies/forms
189+
- Color conversion
190+
191+
### Forms and Structured Data
192+
193+
- Import form data
194+
- Export form data
195+
- Flatten PDF forms
196+
- Convert XFA to Acroforms
197+
198+
## Public API Surface (Repository Context)
199+
200+
- Top-level package exports include:
201+
- `PdfRestClient`
202+
- `AsyncPdfRestClient`
203+
- file clients (`PdfRestFilesClient`, `AsyncPdfRestFilesClient`)
204+
- exception types (for API/auth/request/timeout/transport errors)
205+
- Shared public types live under:
206+
- `pdfrest.types`
207+
- Public models live under:
208+
- `pdfrest.models`
209+
210+
When generating or suggesting code, prefer imports from public modules and
211+
avoid private/underscored modules.
212+
213+
## Examples and Repository Resources
214+
215+
- [Examples README](https://github.com/pdfrest/pdfrest-python/blob/main/examples/README.md):
216+
How to run included examples, including `uv`-based execution.
217+
- [Examples Directory](https://github.com/pdfrest/pdfrest-python/tree/main/examples):
218+
Runnable scripts demonstrating endpoint usage patterns.
219+
- [Repository README](https://github.com/pdfrest/pdfrest-python/blob/main/README.md):
220+
Product-facing overview, install, quickstart, and links.
221+
- [Contributing Guide](https://github.com/pdfrest/pdfrest-python/blob/main/CONTRIBUTING.md):
222+
Developer workflows (lint, type-checking, tests, examples, docs preview).
223+
224+
## Practical Guidance for LLMs and Code Assistants
225+
226+
- Prefer `uv` commands when suggesting modern setup (`uv add pdfrest`,
227+
`uv run ...`), but `pip install pdfrest` is a valid fallback.
228+
- Prefer context-manager usage for clients (`with` / `async with`).
229+
- For local files:
230+
- upload first
231+
- pass `PdfRestFile` objects to endpoint methods
232+
- use `client.files.*` helpers for IO
233+
- Use public imports (`pdfrest`, `pdfrest.types`, `pdfrest.models`) unless a
234+
task explicitly requires internal test-only serialization details.
235+
- For endpoint-specific arguments and literals, consult the Python API reference
236+
and public type definitions before inventing values.
237+
238+
## Change Sensitivity / Freshness
239+
240+
The SDK evolves over time (new endpoints, new payload options, and expanded test
241+
coverage). For latest method availability, supported Python versions, and
242+
release details, prefer:
243+
244+
- [PyPI Package](https://pypi.org/project/pdfrest/)
245+
- [GitHub Repository](https://github.com/pdfrest/pdfrest-python)
246+
- [Python SDK Docs](https://python.pdfrest.com/)

‎docs/llms.txt‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# pdfRest Python SDK Documentation
2+
3+
> Official documentation for the `pdfrest` Python SDK, a typed Python client
4+
> for the pdfRest PDF processing API.
5+
6+
This site documents how to install, configure, and use the Python SDK to call
7+
pdfRest endpoints for PDF conversion, OCR, extraction, redaction, security,
8+
forms, and other document workflows.
9+
10+
The SDK supports both synchronous and asynchronous clients and can target
11+
pdfRest Cloud or self-hosted deployments by changing the client `base_url`.
12+
13+
- [Expanded guide (`llms-full.txt`)](https://python.pdfrest.com/llms-full.txt):
14+
Richer machine-readable overview with docs summaries, workflow patterns, and
15+
integration guidance.
16+
17+
## Primary Docs
18+
19+
- [Getting Started](https://python.pdfrest.com/getting-started/): Install the
20+
SDK, configure `PDFREST_API_KEY`, and make your first API call.
21+
- [Client Configuration](https://python.pdfrest.com/client-configuration/):
22+
Configure API key, base URL, timeouts, logging, and request customization.
23+
- [Using Files](https://python.pdfrest.com/using-files/): Upload, download,
24+
stream, and manage files with the SDK file helpers.
25+
- [API Guide](https://python.pdfrest.com/api-guide/): Practical guidance for
26+
using endpoint helpers and common SDK workflows.
27+
- [API Reference](https://python.pdfrest.com/api-reference/): Generated
28+
reference for the `pdfrest` package, public models, and public types.
29+
30+
## Product and Platform
31+
32+
- [pdfRest Homepage](https://pdfrest.com/): Product overview, capabilities, and
33+
platform positioning.
34+
- [pdfRest API Docs](https://pdfrest.com/apidocs/): Endpoint-level REST API
35+
documentation for the pdfRest platform.
36+
- [API Lab](https://pdfrest.com/apilab/): Interactive environment for testing
37+
pdfRest API endpoints and generating starter code.
38+
- [Product Docs](https://docs.pdfrest.com/): Broader pdfRest documentation,
39+
including deployment options and platform guides.
40+
41+
## Repository
42+
43+
- [GitHub Repository](https://github.com/pdfrest/pdfrest-python): Source code,
44+
examples, tests, CI workflows, and contribution guidelines for this SDK.
45+
- [PyPI Package](https://pypi.org/project/pdfrest/): Package distribution,
46+
release history, and install metadata for `pdfrest`.

0 commit comments

Comments
 (0)