Skip to content

Commit 3ce956d

Browse files
ianardeeianardee
authored
add SKILL file (#339)
1 parent 1916fd1 commit 3ce956d

1 file changed

Lines changed: 182 additions & 0 deletions

File tree

‎SKILL.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Mindee Java SDK
2+
3+
Use this skill for Mindee V2 integrations with the official Java SDK.
4+
5+
## Scope
6+
7+
- Use the official `com.mindee.sdk` Java SDK.
8+
- Focus on SDK-based integration patterns only.
9+
- Do not suggest direct HTTP calls, cURL, or non-SDK integrations.
10+
- Do not use undocumented SDK internals.
11+
12+
## Primary documentation
13+
14+
### SDK overview
15+
- https://docs.mindee.com/integrations/client-libraries-sdk.md
16+
17+
### Client setup
18+
- https://docs.mindee.com/integrations/client-libraries-sdk/configure-the-client.md
19+
20+
### Model parameters
21+
- https://docs.mindee.com/integrations/client-libraries-sdk/basic-model-configuration.md
22+
23+
### Load local files
24+
- https://docs.mindee.com/integrations/client-libraries-sdk/load-and-adjust-a-file.md
25+
26+
### Load remote URLs
27+
- https://docs.mindee.com/integrations/client-libraries-sdk/load-an-url.md
28+
29+
### Send files and URLs
30+
- https://docs.mindee.com/integrations/client-libraries-sdk/send-a-file-or-url.md
31+
32+
### Process responses
33+
- https://docs.mindee.com/integrations/client-libraries-sdk/process-the-response.md
34+
35+
### Handle errors
36+
- https://docs.mindee.com/integrations/problem-database.md
37+
38+
## Handling responses by model type
39+
40+
### Extraction
41+
- Use: https://docs.mindee.com/extraction-models/sdk-integration/extraction-result.md
42+
- Use this page for accessing dynamic fields from `response.getInference().getResult().getFields()`.
43+
- Use this page for examples of `SimpleField`, `ObjectField`, `ListField`, confidence, and locations.
44+
45+
### Split
46+
- Use: https://docs.mindee.com/split-models/sdk-integration/split-result.md
47+
- Use this page for iterating over `response.getInference().getResult().getSplits()`.
48+
- Use this page for examples of `getDocumentType()`, `getPageRange()`, and optional chained extraction results.
49+
50+
### Crop
51+
- Use: https://docs.mindee.com/crop-models/sdk-integration/crop-result.md
52+
- Use this page for iterating over `response.getInference().getResult().getCrops()`.
53+
- Use this page for examples of `getObjectType()`, `getLocation()`, and optional chained extraction results.
54+
55+
### Classification
56+
- Use: https://docs.mindee.com/classification-models/sdk-integration/classification-result.md
57+
- Use this page for accessing `response.getInference().getResult().getClassification()`.
58+
- Use this page for examples of `getDocumentType()`, and optional chained extraction results.
59+
60+
### OCR
61+
- Use: https://docs.mindee.com/raw-text-ocr-models/sdk-integration/ocr-result.md
62+
- Use this page for iterating over `response.getInference().getResult().getPages()`.
63+
- Use this page for page text, words, and word polygon data.
64+
65+
## Default workflow
66+
67+
When answering questions, follow this order:
68+
69+
1. Initialize the SDK client.
70+
2. Configure `modelId` and other inference parameters.
71+
3. Load the input source.
72+
4. Optionally adjust the file before upload.
73+
5. Send with polling or webhooks.
74+
6. Process the response.
75+
7. Handle errors and retries.
76+
77+
## Answering rules
78+
79+
- Base answers on the documentation above.
80+
- Prefer documented SDK methods and patterns.
81+
- Use environment variable `MINDEE_V2_API_KEY` for API keys in production.
82+
- Reuse a client instance when possible.
83+
- Prefer polling (`enqueueAndGetResult()`) for simple examples.
84+
- Prefer webhooks for production or high-volume workflows.
85+
- Declare `throws IOException, InterruptedException` on methods that call polling.
86+
- If a feature is not documented, say it is not officially supported.
87+
- If a user asks for code, keep examples minimal and working.
88+
- This SDK has two API versions: V2 (`com.mindee.v2`) and V1 (`com.mindee.v1`). Default to V2 unless the user asks for V1.
89+
90+
## Code sample rules
91+
92+
- Use Java examples only.
93+
- Use the official Maven artifact `com.mindee.sdk:mindee-api-java`.
94+
- Show imports explicitly.
95+
- Include the exact documented class and method names.
96+
- Use placeholders like `MY_API_KEY`, `MY_MODEL_ID`, and `/path/to/file.pdf`.
97+
- Keep samples focused on one task.
98+
- Use Java 11+ syntax.
99+
100+
## Preferred example topics
101+
102+
### Client initialization
103+
Use:
104+
- `new MindeeClient("MY_API_KEY")` — explicit key (`com.mindee.v2.MindeeClient`)
105+
- `new MindeeClient()` — reads from `MINDEE_V2_API_KEY` environment variable
106+
107+
### Input loading
108+
Use (`com.mindee.input`):
109+
- `new LocalInputSource("path/to/file.pdf")` — from file path
110+
- `new LocalInputSource(new File(...))` — from File object
111+
- `new LocalInputSource(inputStream, "filename.pdf")` — from InputStream
112+
- `new LocalInputSource(byteArray, "filename.pdf")` — from byte array
113+
- `new LocalInputSource(base64String, "filename.pdf")` — from Base64 string
114+
- `URLInputSource.builder("https://...").build()` — from URL
115+
116+
### Sending documents
117+
Use (`com.mindee.v2.MindeeClient`):
118+
- `enqueueAndGetResult(ResponseClass.class, inputSource, parameters)` — polling
119+
- `enqueue(inputSource, parameters)` — for webhooks
120+
121+
### Response handling
122+
Use:
123+
- `response.getInference()` — access the typed inference object
124+
- `response.getInference().getResult()` — access the result fields
125+
- `response.getRawResponse()` — raw JSON string
126+
- `new LocalResponse(file).deserialize(ResponseClass.class)` — for webhook payloads
127+
128+
### File preparation
129+
Use (`com.mindee.input.LocalInputSource`):
130+
- `source.getPageCount()` — count pages
131+
- `source.compress()` — compress before upload
132+
- `source.applyPageOptions(pageOptions)` — trim or remove pages
133+
134+
135+
### Error handling
136+
Use:
137+
- `MindeeException` — base exception (`com.mindee.MindeeException`)
138+
- `MindeeHttpExceptionV2` — HTTP errors with `getStatus()` and `getDetail()` (`com.mindee.v2.http`)
139+
140+
## Avoid
141+
142+
- Direct REST examples
143+
- cURL examples
144+
- Manual authentication header construction
145+
- Bearer token examples for API keys
146+
- Non-Java examples
147+
- V1 examples unless the user explicitly asks for V1
148+
149+
## If the user is unclear
150+
151+
Ask for only what is needed:
152+
153+
- input type: local file or URL
154+
- delivery pattern: polling or webhook
155+
- model ID
156+
- model type: extraction, split, crop, classification, or OCR
157+
158+
## Output style
159+
160+
- Be concise.
161+
- Answer with runnable examples when code is requested.
162+
- Link to the most relevant doc section.
163+
- Do not overwhelm the user with every option.
164+
- Start with the documented default path.
165+
166+
---
167+
168+
# Agent Instructions: Querying The Documentation
169+
170+
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
171+
172+
Perform an HTTP GET request on the documentation URL with the `ask` query parameter.
173+
Include `java+sdk+-+` at the beginning of the question to get answers specific to this library:
174+
175+
```
176+
GET https://docs.mindee.com/integrations.md?ask=java+sdk+-+<question>
177+
```
178+
179+
The question should be specific, self-contained, and written in natural language.
180+
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
181+
182+
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.

0 commit comments

Comments
 (0)