@preapexis/piexis 0.1.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/.github/workflows/publish.yml +35 -0
  2. package/AGENTS.md +21 -41
  3. package/README.md +75 -142
  4. package/extensions/agents.ts +205 -0
  5. package/extensions/ask-question.ts +54 -95
  6. package/extensions/recommended-tools.ts +62 -0
  7. package/extensions/ui.ts +204 -58
  8. package/lib/agent-config.ts +55 -0
  9. package/lib/agents.ts +208 -0
  10. package/lib/question-model.ts +98 -0
  11. package/lib/question-ui.ts +214 -0
  12. package/lib/recommended-tools.ts +119 -0
  13. package/lib/subagent-runner.ts +146 -0
  14. package/lib/ui-tips.json +41 -0
  15. package/package.json +9 -12
  16. package/prompts/init.md +10 -2
  17. package/prompts/summary.md +7 -6
  18. package/schemas/agent.schema.json +48 -0
  19. package/scripts/release.mjs +32 -0
  20. package/skills/{claude-api/LICENSE.txt → caveman/LICENSE} +2 -2
  21. package/skills/caveman/LICENSE-MIT +21 -0
  22. package/skills/caveman/NOTICE +10 -0
  23. package/skills/caveman/SKILL.md +89 -0
  24. package/skills/find-skills/SKILL.md +141 -0
  25. package/skills/ponytail/LICENSE +21 -0
  26. package/skills/ponytail/NOTICE +9 -0
  27. package/skills/ponytail/SKILL.md +52 -0
  28. package/skills-lock.json +6 -0
  29. package/tests/agents.test.mjs +605 -0
  30. package/tests/ask-question-pty.test.mjs +16 -0
  31. package/tests/ask-question.test.mjs +269 -0
  32. package/tests/fixtures/agents-provider.ts +55 -0
  33. package/tests/fixtures/ask-question-pty.py +91 -0
  34. package/tests/fixtures/ask-question-terminal.mjs +69 -0
  35. package/tests/fixtures/recommended-tools-terminal.mjs +103 -0
  36. package/tests/init-workflow.test.mjs +31 -0
  37. package/tests/recommended-tools-pty.test.mjs +16 -0
  38. package/tests/recommended-tools.test.mjs +423 -0
  39. package/tests/resources.test.mjs +66 -0
  40. package/tests/skills-routing.test.mjs +7 -4
  41. package/tests/ui-tip-reload.test.mjs +70 -0
  42. package/tests/ui.test.mjs +450 -0
  43. package/tsconfig.json +1 -0
  44. package/.github/workflows/npm-publish.yml +0 -63
  45. package/PERMISSION_MODES_PLAN.md +0 -279
  46. package/WHAT_YOU_GET.md +0 -153
  47. package/eval/README.md +0 -72
  48. package/eval/permission-cases.json +0 -28
  49. package/eval/permissions.mjs +0 -103
  50. package/extensions/background-tasks.ts +0 -433
  51. package/extensions/background-worker.ts +0 -50
  52. package/extensions/glob.ts +0 -32
  53. package/extensions/mode.ts +0 -397
  54. package/lib/bash-approvals.ts +0 -113
  55. package/lib/bash-policy.ts +0 -164
  56. package/lib/mode-policy.ts +0 -174
  57. package/lib/path-policy.ts +0 -182
  58. package/lib/permission-classifier.ts +0 -128
  59. package/lib/permission-config.ts +0 -91
  60. package/lib/permission-denials.ts +0 -32
  61. package/lib/permission-intent.ts +0 -128
  62. package/lib/permission-taxonomy.ts +0 -15
  63. package/lib/task-broker.ts +0 -65
  64. package/lib/task-checkout.ts +0 -39
  65. package/lib/task-git.ts +0 -44
  66. package/lib/task-patch.ts +0 -106
  67. package/lib/task-permissions.ts +0 -51
  68. package/lib/task-report.ts +0 -62
  69. package/lib/task-worktree-policy.ts +0 -56
  70. package/skills/claude-api/SKILL.md +0 -572
  71. package/skills/claude-api/csharp/claude-api/README.md +0 -362
  72. package/skills/claude-api/csharp/claude-api/batches.md +0 -14
  73. package/skills/claude-api/csharp/claude-api/files-api.md +0 -25
  74. package/skills/claude-api/csharp/claude-api/streaming.md +0 -28
  75. package/skills/claude-api/csharp/claude-api/tool-use.md +0 -164
  76. package/skills/claude-api/curl/examples.md +0 -256
  77. package/skills/claude-api/curl/managed-agents.md +0 -371
  78. package/skills/claude-api/go/claude-api/README.md +0 -188
  79. package/skills/claude-api/go/claude-api/files-api.md +0 -23
  80. package/skills/claude-api/go/claude-api/streaming.md +0 -43
  81. package/skills/claude-api/go/claude-api/tool-use.md +0 -220
  82. package/skills/claude-api/go/managed-agents/README.md +0 -564
  83. package/skills/claude-api/java/claude-api/README.md +0 -238
  84. package/skills/claude-api/java/claude-api/files-api.md +0 -27
  85. package/skills/claude-api/java/claude-api/streaming.md +0 -24
  86. package/skills/claude-api/java/claude-api/tool-use.md +0 -228
  87. package/skills/claude-api/java/managed-agents/README.md +0 -443
  88. package/skills/claude-api/php/claude-api/README.md +0 -174
  89. package/skills/claude-api/php/claude-api/batches.md +0 -15
  90. package/skills/claude-api/php/claude-api/files-api.md +0 -13
  91. package/skills/claude-api/php/claude-api/streaming.md +0 -27
  92. package/skills/claude-api/php/claude-api/tool-use.md +0 -253
  93. package/skills/claude-api/php/managed-agents/README.md +0 -443
  94. package/skills/claude-api/python/claude-api/README.md +0 -565
  95. package/skills/claude-api/python/claude-api/batches.md +0 -198
  96. package/skills/claude-api/python/claude-api/files-api.md +0 -170
  97. package/skills/claude-api/python/claude-api/sdk-upgrade.md +0 -286
  98. package/skills/claude-api/python/claude-api/streaming.md +0 -179
  99. package/skills/claude-api/python/claude-api/tool-use.md +0 -627
  100. package/skills/claude-api/python/managed-agents/README.md +0 -335
  101. package/skills/claude-api/ruby/claude-api/README.md +0 -134
  102. package/skills/claude-api/ruby/claude-api/streaming.md +0 -16
  103. package/skills/claude-api/ruby/claude-api/tool-use.md +0 -41
  104. package/skills/claude-api/ruby/managed-agents/README.md +0 -394
  105. package/skills/claude-api/shared/admin-api.md +0 -179
  106. package/skills/claude-api/shared/agent-design.md +0 -101
  107. package/skills/claude-api/shared/anthropic-cli.md +0 -269
  108. package/skills/claude-api/shared/claude-platform-on-aws.md +0 -59
  109. package/skills/claude-api/shared/cost-optimization.md +0 -233
  110. package/skills/claude-api/shared/error-codes.md +0 -262
  111. package/skills/claude-api/shared/live-sources.md +0 -166
  112. package/skills/claude-api/shared/managed-agents-api-reference.md +0 -455
  113. package/skills/claude-api/shared/managed-agents-client-patterns.md +0 -220
  114. package/skills/claude-api/shared/managed-agents-core.md +0 -359
  115. package/skills/claude-api/shared/managed-agents-environments.md +0 -226
  116. package/skills/claude-api/shared/managed-agents-events.md +0 -290
  117. package/skills/claude-api/shared/managed-agents-memory.md +0 -201
  118. package/skills/claude-api/shared/managed-agents-multiagent.md +0 -260
  119. package/skills/claude-api/shared/managed-agents-onboarding.md +0 -82
  120. package/skills/claude-api/shared/managed-agents-outcomes.md +0 -108
  121. package/skills/claude-api/shared/managed-agents-overview.md +0 -77
  122. package/skills/claude-api/shared/managed-agents-scheduled-deployments.md +0 -156
  123. package/skills/claude-api/shared/managed-agents-self-hosted-sandboxes.md +0 -282
  124. package/skills/claude-api/shared/managed-agents-tools.md +0 -504
  125. package/skills/claude-api/shared/managed-agents-webhooks.md +0 -143
  126. package/skills/claude-api/shared/model-migration.md +0 -1872
  127. package/skills/claude-api/shared/models.md +0 -142
  128. package/skills/claude-api/shared/platform-availability.md +0 -53
  129. package/skills/claude-api/shared/prompt-audit.md +0 -223
  130. package/skills/claude-api/shared/prompt-caching.md +0 -292
  131. package/skills/claude-api/shared/token-counting.md +0 -56
  132. package/skills/claude-api/shared/tool-use-concepts.md +0 -526
  133. package/skills/claude-api/typescript/claude-api/README.md +0 -405
  134. package/skills/claude-api/typescript/claude-api/batches.md +0 -106
  135. package/skills/claude-api/typescript/claude-api/files-api.md +0 -98
  136. package/skills/claude-api/typescript/claude-api/streaming.md +0 -178
  137. package/skills/claude-api/typescript/claude-api/tool-use.md +0 -586
  138. package/skills/claude-api/typescript/managed-agents/README.md +0 -359
  139. package/tests/auto-permissions.test.mjs +0 -315
  140. package/tests/background-tasks.test.mjs +0 -27
  141. package/tests/background-worker.test.mjs +0 -60
  142. package/tests/bash-permissions.test.mjs +0 -276
  143. package/tests/glob.test.mjs +0 -31
  144. package/tests/mode.test.mjs +0 -62
  145. package/tests/permission-evaluation.test.mjs +0 -70
  146. package/tests/permission-foundation.test.mjs +0 -194
  147. package/tests/permission-policy.test.mjs +0 -158
  148. package/tests/runtime/README.md +0 -51
  149. package/tests/runtime/harness.mjs +0 -190
  150. package/tests/runtime/permissions.test.mjs +0 -192
  151. package/tests/runtime/tui.test.mjs +0 -60
  152. package/tests/task-integration.test.mjs +0 -324
  153. package/tests/task-permissions.test.mjs +0 -178
  154. package/tests/task-worktree-policy.test.mjs +0 -53
@@ -1,238 +0,0 @@
1
- # Claude API - Java
2
-
3
- > **Note:** The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java.
4
-
5
- ## Package Reference
6
-
7
- Types are organized by package. If a class you need isn't shown in an example below, locate it via this table first - don't block on fetching SDK source over the network.
8
-
9
- | `import` prefix | Contains |
10
- |---|---|
11
- | `com.anthropic.client` / `com.anthropic.client.okhttp` | `AnthropicClient`, `AnthropicOkHttpClient` |
12
- | `com.anthropic.models.messages` | non-beta request/response types - `MessageCreateParams`, `Model`, `Message`, `TextBlockParam`, `ContentBlockParam`, `ToolUseBlockParam`, `ToolResultBlockParam`, `CacheControlEphemeral`, `Tool*` (e.g. `ToolBash20250124`, `ToolTextEditor20250728`), `StopReason`, `StructuredMessage*` |
13
- | `com.anthropic.models.messages.batches` | Batch API - `BatchResultsParams`, `MessageBatchIndividualResponse` |
14
- | `com.anthropic.models.beta` | `AnthropicBeta` (beta-flag constants) |
15
- | `com.anthropic.models.beta.messages` | beta-endpoint types - `MessageCreateParams`, `BetaMessage`, `BetaStopReason`, `BetaContextManagementConfig`, `BetaMcpToolset`, `BetaRequestMcpServerUrlDefinition`, `BetaTool*` |
16
- | `com.anthropic.core` | `JsonValue`, `JsonField`, `JsonSchemaLocalValidation`, `com.anthropic.core.http.StreamResponse` |
17
- | `com.anthropic.errors` | typed exceptions - `AnthropicServiceException`, `RateLimitException`, `NotFoundException`, etc. (see `shared/error-codes.md`) |
18
-
19
- `client.messages()` uses `com.anthropic.models.messages.*`; `client.beta().messages()` uses `com.anthropic.models.beta.messages.*`. Both packages define a `MessageCreateParams` - import the one matching the client path you call.
20
-
21
- ### Key types per feature
22
-
23
- Write from this table instead of `javap`/jar inspection. Endpoint column tells you whether to use `client.messages()` or `client.beta().messages()`.
24
-
25
- | Feature | Endpoint | Key Java types / builder calls |
26
- |---|---|---|
27
- | User profiles | beta | `client.beta().userProfiles().create(...)` / `.retrieve(id)` / `.list()`. Pass the returned profile id on the beta `MessageCreateParams`. Requires a beta header - check the SDK's beta-headers reference for the current flag. |
28
- | Agent Skills | beta | `BetaContainerParams`, `BetaSkillParams`, `BetaCodeExecutionTool20250825`. `.addBeta("code-execution-2025-08-25")` (Skills is out of beta - no `skills-2025-10-02`). Download the output via `client.beta().files().download(fileId)`. |
29
- | Cache diagnostics | beta | `BetaDiagnosticsParam`, `BetaCacheControlEphemeral` |
30
- | Context editing | beta | `.contextManagement(BetaContextManagementConfig.builder()...)`. The edit strategy is a `BetaClearToolUses20250919Edit` (or `BetaClearThinking20251015Edit`); its trigger is a `BetaInputTokensTrigger` built separately and passed to the edit's builder - there is no direct `.inputTokensTrigger(N)` shortcut on the edit builder. `javap` the edit and trigger classes for the exact setter names. |
31
- | Memory tool | non-beta | `.addTool(MemoryTool20250818.builder().build())` from `com.anthropic.models.messages` |
32
- | Programmatic tool calling | non-beta | `CodeExecutionTool20260120`, `Tool`, `ContentBlockParam` |
33
- | Strict tool use | non-beta | `Tool`, `Tool.InputSchema` |
34
- | Task budgets | beta | `.outputConfig(BetaOutputConfig.builder().taskBudget(BetaTokenTaskBudget.builder()...))` |
35
- | Tool search | non-beta | `.addTool(ToolSearchToolRegex20251119.builder()...)` from `com.anthropic.models.messages` |
36
- | Web search | non-beta | `WebSearchTool20260209` from `com.anthropic.models.messages` - the latest variant with dynamic filtering (Claude Fable 5.1 + Claude Opus 5 + Opus 4.8/4.7/4.6 + Claude Sonnet 5 + Sonnet 4.6). For older models or Vertex, use `WebSearchTool20250305` |
37
-
38
- ### Discovering type and member names
39
-
40
- If a class or builder method you need isn't in the tables above, `jar tf <anthropic-java-core jar> | grep -i <term>` or `javap -classpath <jar> com.anthropic.models....` is fast enough to locate names. **Do not compile and run a separate reflection program** to enumerate members - the first build is slow enough to be backgrounded in many environments, trapping you in a polling loop. Write the script with the names you found and let the compiler error (`cannot find symbol`) point at any wrong member.
41
-
42
- ## Installation
43
-
44
- Maven:
45
-
46
- ```xml
47
- <dependency>
48
- <groupId>com.anthropic</groupId>
49
- <artifactId>anthropic-java</artifactId>
50
- <version>2.34.0</version>
51
- </dependency>
52
- ```
53
-
54
- Gradle:
55
-
56
- ```groovy
57
- implementation("com.anthropic:anthropic-java:2.34.0")
58
- ```
59
-
60
- ## Client Initialization
61
-
62
- ```java
63
- import com.anthropic.client.AnthropicClient;
64
- import com.anthropic.client.okhttp.AnthropicOkHttpClient;
65
-
66
- // Default (reads ANTHROPIC_API_KEY from environment)
67
- AnthropicClient client = AnthropicOkHttpClient.fromEnv();
68
-
69
- // Explicit API key
70
- AnthropicClient client = AnthropicOkHttpClient.builder()
71
- .apiKey("your-api-key")
72
- .build();
73
- ```
74
-
75
- ---
76
-
77
- ## Basic Message Request
78
-
79
- ```java
80
- import com.anthropic.models.messages.MessageCreateParams;
81
- import com.anthropic.models.messages.Message;
82
-
83
- MessageCreateParams params = MessageCreateParams.builder()
84
- .model("claude-opus-5") // .model(String) overload - use it for ids with no typed Model constant yet
85
- .maxTokens(16000L)
86
- .addUserMessage("What is the capital of France?")
87
- .build();
88
-
89
- Message response = client.messages().create(params);
90
- response.content().stream()
91
- .flatMap(block -> block.text().stream())
92
- .forEach(textBlock -> System.out.println(textBlock.text()));
93
- ```
94
-
95
- ---
96
-
97
- ## Thinking
98
-
99
- **Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. The builder has a direct `.thinking(ThinkingConfigAdaptive)` overload - no manual union wrapping.
100
-
101
- > **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (below). `ThinkingConfigEnabled.builder().budgetTokens(N)` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
102
- > **Claude Opus 5:** thinking is on by default - omitting `.thinking(...)` runs adaptive (`ThinkingConfigAdaptive` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `ThinkingConfigDisabled` is accepted only at effort `HIGH` or lower; pairing it with `XHIGH`/`MAX` returns a 400.
103
- > **Older models:** Use `.thinking(ThinkingConfigEnabled.builder().budgetTokens(N).build())` (budget must be < `maxTokens`, min 1024).
104
-
105
- ```java
106
- import com.anthropic.models.messages.ContentBlock;
107
- import com.anthropic.models.messages.MessageCreateParams;
108
- import com.anthropic.models.messages.Model;
109
- import com.anthropic.models.messages.ThinkingConfigAdaptive;
110
-
111
- MessageCreateParams params = MessageCreateParams.builder()
112
- .model(Model.CLAUDE_SONNET_4_6)
113
- .maxTokens(16000L)
114
- .thinking(ThinkingConfigAdaptive.builder().build())
115
- .addUserMessage("Solve this step by step: 27 * 453")
116
- .build();
117
-
118
- for (ContentBlock block : client.messages().create(params).content()) {
119
- block.thinking().ifPresent(t -> System.out.println("[thinking] " + t.thinking()));
120
- block.text().ifPresent(t -> System.out.println(t.text()));
121
- }
122
- ```
123
-
124
- `ContentBlock` narrowing: `.thinking()` / `.text()` return `Optional<T>` - use `.ifPresent(...)` or `.stream().flatMap(...)`. Alternative: `isThinking()` / `asThinking()` boolean+unwrap pairs (throws on wrong variant).
125
-
126
- ---
127
-
128
- ## Effort Parameter
129
-
130
- Effort is nested inside `OutputConfig` - there is NO `.effort()` directly on `MessageCreateParams.Builder`.
131
-
132
- ```java
133
- import com.anthropic.models.messages.OutputConfig;
134
-
135
- .outputConfig(OutputConfig.builder()
136
- .effort(OutputConfig.Effort.HIGH) // or LOW, MEDIUM, XHIGH, MAX
137
- .build())
138
- ```
139
-
140
- Combine with `Thinking = ThinkingConfigAdaptive` for cost-quality control.
141
-
142
- ---
143
-
144
- ## Prompt Caching
145
-
146
- System message as a list of `TextBlockParam` with `CacheControlEphemeral`. Use `.systemOfTextBlockParams(...)` - the plain `.system(String)` overload can't carry cache control. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
147
-
148
- ```java
149
- import com.anthropic.models.messages.TextBlockParam;
150
- import com.anthropic.models.messages.CacheControlEphemeral;
151
-
152
- .systemOfTextBlockParams(List.of(
153
- TextBlockParam.builder()
154
- .text(longSystemPrompt)
155
- .cacheControl(CacheControlEphemeral.builder()
156
- .ttl(CacheControlEphemeral.Ttl.TTL_1H) // optional; also TTL_5M
157
- .build())
158
- .build()))
159
- ```
160
-
161
- There's also a top-level `.cacheControl(CacheControlEphemeral)` on `MessageCreateParams.Builder` and on `Tool.builder()`.
162
-
163
- Verify hits via `response.usage().cacheCreationInputTokens()` / `response.usage().cacheReadInputTokens()`.
164
-
165
- ---
166
-
167
- ## Token Counting
168
-
169
- ```java
170
- import com.anthropic.models.messages.MessageCountTokensParams;
171
-
172
- long tokens = client.messages().countTokens(
173
- MessageCountTokensParams.builder()
174
- .model(Model.CLAUDE_SONNET_4_6)
175
- .addUserMessage("Hello")
176
- .build()
177
- ).inputTokens();
178
- ```
179
-
180
- ---
181
-
182
- ## PDF / Document Input
183
-
184
- `DocumentBlockParam` builder has source shortcuts. Wrap in `ContentBlockParam.ofDocument()` and pass via `.addUserMessageOfBlockParams()`.
185
-
186
- ```java
187
- import com.anthropic.models.messages.DocumentBlockParam;
188
- import com.anthropic.models.messages.ContentBlockParam;
189
- import com.anthropic.models.messages.TextBlockParam;
190
-
191
- DocumentBlockParam doc = DocumentBlockParam.builder()
192
- .source(Base64PdfSource.builder().data(base64String).build())
193
- // or .source(UrlPdfSource.builder().url("https://...").build())
194
- .title("My Document") // optional
195
- .build();
196
- ```
197
-
198
- For **Files API** document references, use the beta path and beta types - see `files-api.md`: `BetaRequestDocumentBlock.builder().source(BetaFileDocumentSource.builder().fileId(id).build())`.
199
-
200
- ```java
201
- .addUserMessageOfBlockParams(List.of(
202
- ContentBlockParam.ofDocument(doc),
203
- ContentBlockParam.ofText(TextBlockParam.builder().text("Summarize this").build())))
204
- ```
205
-
206
- ---
207
-
208
- ## Stop Details
209
-
210
- When `stopReason()` is `"refusal"`, the response includes structured `stopDetails()`:
211
-
212
- ```java
213
- response.stopDetails().ifPresent(details -> {
214
- System.out.println("Category: " + details.category());
215
- System.out.println("Explanation: " + details.explanation());
216
- });
217
- ```
218
-
219
- **Refusal fallbacks (Claude Fable 5.1) - opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. New `claude-fable-5-1` code should include the server-side `fallbacks` parameter (beta header `server-side-fallback-2026-06-01`, fallback model `claude-opus-4-8`, on the beta messages call) by default. The exact Java builder methods (and the client-side middleware for providers without server-side support) are not documented here - WebFetch the Java SDK repo's `examples/` from `shared/live-sources.md`; full semantics in `shared/model-migration.md` -> Migrating to Claude Fable 5.1 -> `refusal` stop reason.
220
-
221
- ---
222
-
223
- ## Error Type
224
-
225
- `AnthropicServiceException` exposes `.errorType()` returning `Optional<ErrorType>` for programmatic error classification:
226
-
227
- ```java
228
- try {
229
- client.messages().create(params);
230
- } catch (AnthropicServiceException e) {
231
- e.errorType().ifPresent(type ->
232
- System.out.println("Error type: " + type) // RATE_LIMIT_ERROR, OVERLOADED_ERROR, etc.
233
- );
234
- }
235
- ```
236
-
237
- ---
238
-
@@ -1,27 +0,0 @@
1
- # Files API - Java
2
-
3
- ## Files API
4
-
5
- > **Out of beta.** In current SDKs `client.beta().files()` has breaking shape changes from previous versions, matching the stable `client.files()` - migrate per the Files API row in `shared/live-sources.md`. Examples below predate this.
6
-
7
- Under `client.beta().files()`. File references in messages need the beta message types (non-beta `DocumentBlockParam.Source` has no file-ID variant).
8
-
9
- ```java
10
- import com.anthropic.models.beta.files.FileUploadParams;
11
- import com.anthropic.models.beta.files.FileMetadata;
12
- import com.anthropic.models.beta.messages.BetaRequestDocumentBlock;
13
- import com.anthropic.models.beta.messages.BetaFileDocumentSource;
14
- import java.nio.file.Paths;
15
-
16
- FileMetadata meta = client.beta().files().upload(
17
- FileUploadParams.builder()
18
- .file(Paths.get("/path/to/doc.pdf")) // or .file(InputStream) or .file(byte[])
19
- .build());
20
-
21
- // Reference in a beta message:
22
- BetaRequestDocumentBlock doc = BetaRequestDocumentBlock.builder()
23
- .source(BetaFileDocumentSource.builder().fileId(meta.id()).build())
24
- .build();
25
- ```
26
-
27
- Other methods: `.list()`, `.delete(String fileId)`, `.download(String fileId)`, `.retrieveMetadata(String fileId)`.
@@ -1,24 +0,0 @@
1
- # Streaming - Java
2
-
3
- ## Streaming
4
-
5
- ```java
6
- import com.anthropic.core.http.StreamResponse;
7
- import com.anthropic.models.messages.RawMessageStreamEvent;
8
-
9
- MessageCreateParams params = MessageCreateParams.builder()
10
- .model(Model.CLAUDE_OPUS_4_8)
11
- .maxTokens(64000L)
12
- .addUserMessage("Write a haiku")
13
- .build();
14
-
15
- try (StreamResponse<RawMessageStreamEvent> streamResponse = client.messages().createStreaming(params)) {
16
- streamResponse.stream()
17
- .flatMap(event -> event.contentBlockDelta().stream())
18
- .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
19
- .forEach(textDelta -> System.out.print(textDelta.text()));
20
- }
21
- ```
22
-
23
- ---
24
-
@@ -1,228 +0,0 @@
1
- # Tool Use - Java
2
-
3
- For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
4
-
5
- ## Tool Use (Beta)
6
-
7
- The Java SDK supports beta tool use with annotated classes. Tool classes implement `Supplier<String>` for automatic execution via `BetaToolRunner`.
8
-
9
- ### Tool Runner (automatic loop)
10
-
11
- ```java
12
- import com.anthropic.models.beta.messages.MessageCreateParams;
13
- import com.anthropic.models.beta.messages.BetaMessage;
14
- import com.anthropic.helpers.BetaToolRunner;
15
- import com.fasterxml.jackson.annotation.JsonClassDescription;
16
- import com.fasterxml.jackson.annotation.JsonPropertyDescription;
17
- import java.util.function.Supplier;
18
-
19
- @JsonClassDescription("Get the weather in a given location")
20
- static class GetWeather implements Supplier<String> {
21
- @JsonPropertyDescription("The city and state, e.g. San Francisco, CA")
22
- public String location;
23
-
24
- @Override
25
- public String get() {
26
- return "The weather in " + location + " is sunny and 72°F";
27
- }
28
- }
29
-
30
- BetaToolRunner toolRunner = client.beta().messages().toolRunner(
31
- MessageCreateParams.builder()
32
- .model("claude-opus-5")
33
- .maxTokens(16000L)
34
- .putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13")
35
- .addTool(GetWeather.class)
36
- .addUserMessage("What's the weather in San Francisco?")
37
- .build());
38
-
39
- for (BetaMessage message : toolRunner) {
40
- System.out.println(message);
41
- }
42
- ```
43
-
44
- ### Memory Tool
45
-
46
- The Java SDK provides `BetaMemoryToolHandler` for implementing the memory tool backend. You supply a handler that manages file storage, and the `BetaToolRunner` handles memory tool calls automatically.
47
-
48
- ```java
49
- import com.anthropic.helpers.BetaMemoryToolHandler;
50
- import com.anthropic.helpers.BetaToolRunner;
51
- import com.anthropic.models.beta.messages.BetaMemoryTool20250818;
52
- import com.anthropic.models.beta.messages.BetaMessage;
53
- import com.anthropic.models.beta.messages.MessageCreateParams;
54
- import com.anthropic.models.beta.messages.ToolRunnerCreateParams;
55
-
56
- // Implement BetaMemoryToolHandler with your storage backend (e.g., filesystem)
57
- BetaMemoryToolHandler memoryHandler = new FileSystemMemoryToolHandler(sandboxRoot);
58
-
59
- MessageCreateParams createParams = MessageCreateParams.builder()
60
- .model("claude-opus-5")
61
- .maxTokens(4096L)
62
- .addTool(BetaMemoryTool20250818.builder().build())
63
- .addUserMessage("Remember that my favorite color is blue")
64
- .build();
65
-
66
- BetaToolRunner toolRunner = client.beta().messages().toolRunner(
67
- ToolRunnerCreateParams.builder()
68
- .betaMemoryToolHandler(memoryHandler)
69
- .initialMessageParams(createParams)
70
- .build());
71
-
72
- for (BetaMessage message : toolRunner) {
73
- System.out.println(message);
74
- }
75
- ```
76
-
77
- See the [shared memory tool concepts](../../shared/tool-use-concepts.md) for more details on the memory tool.
78
-
79
- ### Non-Beta Tool Declaration (manual JSON schema)
80
-
81
- `Tool.InputSchema.Properties` is a freeform `Map<String, JsonValue>` wrapper - build property schemas via `putAdditionalProperty`. `type: "object"` is the default. The builder has a direct `.addTool(Tool)` overload that wraps in `ToolUnion` automatically.
82
-
83
- ```java
84
- import com.anthropic.core.JsonValue;
85
- import com.anthropic.models.messages.Tool;
86
-
87
- Tool tool = Tool.builder()
88
- .name("get_weather")
89
- .description("Get the current weather in a given location")
90
- .inputSchema(Tool.InputSchema.builder()
91
- .properties(Tool.InputSchema.Properties.builder()
92
- .putAdditionalProperty("location", JsonValue.from(Map.of("type", "string")))
93
- .build())
94
- .required(List.of("location"))
95
- .build())
96
- .build();
97
-
98
- MessageCreateParams params = MessageCreateParams.builder()
99
- .model(Model.CLAUDE_SONNET_4_6)
100
- .maxTokens(16000L)
101
- .addTool(tool)
102
- .addUserMessage("Weather in Paris?")
103
- .build();
104
- ```
105
-
106
- For manual tool loops, handle `tool_use` blocks in the response, send `tool_result` back, loop until `stop_reason` is `"end_turn"`. See [shared tool use concepts](../../shared/tool-use-concepts.md).
107
-
108
- ### Building `MessageParam` with Content Blocks (Tool Result Round-Trip)
109
-
110
- `MessageParam.Content` is an inner union class (string | list). Use the builder's `.contentOfBlockParams(List<ContentBlockParam>)` alias - there is NO separate `MessageParamContent` class with a static `ofBlockParams`:
111
-
112
- ```java
113
- import com.anthropic.models.messages.MessageParam;
114
- import com.anthropic.models.messages.ContentBlockParam;
115
- import com.anthropic.models.messages.ToolResultBlockParam;
116
-
117
- List<ContentBlockParam> results = List.of(
118
- ContentBlockParam.ofToolResult(ToolResultBlockParam.builder()
119
- .toolUseId(toolUseBlock.id())
120
- .content(yourResultString)
121
- .build())
122
- );
123
-
124
- MessageParam toolResultMsg = MessageParam.builder()
125
- .role(MessageParam.Role.USER)
126
- .contentOfBlockParams(results) // builder alias for Content.ofBlockParams(...)
127
- .build();
128
- ```
129
-
130
- ---
131
-
132
- ## Structured Output
133
-
134
- The class-based overload auto-derives the JSON schema from your POJO and gives you a typed `.text()` return - no manual schema, no manual parsing.
135
-
136
- ```java
137
- import com.anthropic.models.messages.StructuredMessageCreateParams;
138
-
139
- record Book(String title, String author) {}
140
- record BookList(List<Book> books) {}
141
-
142
- StructuredMessageCreateParams<BookList> params = MessageCreateParams.builder()
143
- .model(Model.CLAUDE_SONNET_4_6)
144
- .maxTokens(16000L)
145
- .outputConfig(BookList.class) // returns a typed builder
146
- .addUserMessage("List 3 classic novels")
147
- .build();
148
-
149
- client.messages().create(params).content().stream()
150
- .flatMap(cb -> cb.text().stream())
151
- .forEach(typed -> {
152
- // typed.text() returns BookList, not String
153
- for (Book b : typed.text().books()) System.out.println(b.title());
154
- });
155
- ```
156
-
157
- Supports Jackson annotations: `@JsonPropertyDescription`, `@JsonIgnore`, `@ArraySchema(minItems=...)`. Manual schema path: `OutputConfig.builder().format(JsonOutputFormat.builder().schema(...).build())`.
158
-
159
- ---
160
-
161
- ## Anthropic-Defined Tools
162
-
163
- Version-suffixed types; `name`/`type` auto-set by builder. Direct `.addTool()` overloads exist for most tool types; where one is missing (newer or less-common tools - see the advisor note below), wrap via the union type's static factory: `.addTool(BetaToolUnion.of<ToolName>(builder...build()))`. Web search and code execution are server-executed; bash and text editor are client-executed (you handle the `tool_use` locally - see `shared/tool-use-concepts.md`).
164
-
165
- ```java
166
- import com.anthropic.models.messages.WebSearchTool20260209;
167
- import com.anthropic.models.messages.ToolBash20250124;
168
- import com.anthropic.models.messages.ToolTextEditor20250728;
169
- import com.anthropic.models.messages.CodeExecutionTool20260120;
170
-
171
- .addTool(WebSearchTool20260209.builder()
172
- .maxUses(5L) // optional
173
- .allowedDomains(List.of("example.com")) // optional
174
- .build())
175
- .addTool(ToolBash20250124.builder().build())
176
- .addTool(ToolTextEditor20250728.builder().build())
177
- .addTool(CodeExecutionTool20260120.builder().build())
178
- ```
179
-
180
- Also available: `WebFetchTool20260209`, `MemoryTool20250818`, `ToolSearchToolBm25_20251119`. For the advisor tool, use `BetaAdvisorTool20260301` in the beta namespace with `.addBeta("advisor-tool-2026-03-01")` (server-side; advisor model >= executor model). There is no direct `.addTool(BetaAdvisorTool20260301)` overload on the beta builder - wrap it via the `BetaToolUnion` static factory for the advisor type; if `javac` rejects the specific factory method name, `javap com.anthropic.models.beta.messages.BetaToolUnion | grep -i advisor` shows the exact one.
181
-
182
- ### Beta namespace (MCP, compaction)
183
-
184
- For beta-only features use `com.anthropic.models.beta.messages.*` - class names have a `Beta` prefix AND live in the beta package. The beta `MessageCreateParams.Builder` has direct `.addTool(BetaToolBash20250124)` overloads AND `.addMcpServer()`:
185
-
186
- ```java
187
- import com.anthropic.models.beta.messages.MessageCreateParams;
188
- import com.anthropic.models.beta.messages.BetaToolBash20250124;
189
- import com.anthropic.models.beta.messages.BetaCodeExecutionTool20260120;
190
- import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
191
-
192
- MessageCreateParams params = MessageCreateParams.builder()
193
- .model(Model.CLAUDE_OPUS_4_8)
194
- .maxTokens(16000L)
195
- .addBeta("mcp-client-2025-11-20")
196
- .addTool(BetaToolBash20250124.builder().build())
197
- .addTool(BetaCodeExecutionTool20260120.builder().build())
198
- .addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
199
- .name("my-server")
200
- .url("https://example.com/mcp")
201
- .build())
202
- .addUserMessage("...")
203
- .build();
204
-
205
- client.beta().messages().create(params);
206
- ```
207
-
208
- `BetaTool*` types are NOT interchangeable with non-beta `Tool*` - pick one namespace per request.
209
-
210
- **Reading server-tool blocks in the response:** `ServerToolUseBlock` has `.id()`, `.name()` (enum), and `._input()` returning raw `JsonValue` - there is NO typed `.input()`. For code execution results, unwrap two levels:
211
-
212
- ```java
213
- for (ContentBlock block : response.content()) {
214
- block.serverToolUse().ifPresent(stu -> {
215
- System.out.println("tool: " + stu.name() + " input: " + stu._input());
216
- });
217
- block.codeExecutionToolResult().ifPresent(r -> {
218
- r.content().resultBlock().ifPresent(result -> {
219
- System.out.println("stdout: " + result.stdout());
220
- System.out.println("stderr: " + result.stderr());
221
- System.out.println("exit: " + result.returnCode());
222
- });
223
- });
224
- }
225
- ```
226
-
227
- ---
228
-