@preapexis/piexis 0.2.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 (149) hide show
  1. package/AGENTS.md +21 -41
  2. package/README.md +73 -139
  3. package/extensions/agents.ts +205 -0
  4. package/extensions/ask-question.ts +54 -95
  5. package/extensions/recommended-tools.ts +62 -0
  6. package/extensions/ui.ts +204 -58
  7. package/lib/agent-config.ts +55 -0
  8. package/lib/agents.ts +208 -0
  9. package/lib/question-model.ts +98 -0
  10. package/lib/question-ui.ts +214 -0
  11. package/lib/recommended-tools.ts +119 -0
  12. package/lib/subagent-runner.ts +146 -0
  13. package/lib/ui-tips.json +41 -0
  14. package/package.json +5 -13
  15. package/prompts/init.md +10 -2
  16. package/prompts/summary.md +7 -6
  17. package/schemas/agent.schema.json +48 -0
  18. package/skills/{claude-api/LICENSE.txt → caveman/LICENSE} +2 -2
  19. package/skills/caveman/LICENSE-MIT +21 -0
  20. package/skills/caveman/NOTICE +10 -0
  21. package/skills/caveman/SKILL.md +89 -0
  22. package/skills/find-skills/SKILL.md +141 -0
  23. package/skills/ponytail/LICENSE +21 -0
  24. package/skills/ponytail/NOTICE +9 -0
  25. package/skills/ponytail/SKILL.md +52 -0
  26. package/skills-lock.json +6 -0
  27. package/tests/agents.test.mjs +605 -0
  28. package/tests/ask-question-pty.test.mjs +16 -0
  29. package/tests/ask-question.test.mjs +269 -0
  30. package/tests/fixtures/agents-provider.ts +55 -0
  31. package/tests/fixtures/ask-question-pty.py +91 -0
  32. package/tests/fixtures/ask-question-terminal.mjs +69 -0
  33. package/tests/fixtures/recommended-tools-terminal.mjs +103 -0
  34. package/tests/init-workflow.test.mjs +31 -0
  35. package/tests/recommended-tools-pty.test.mjs +16 -0
  36. package/tests/recommended-tools.test.mjs +423 -0
  37. package/tests/resources.test.mjs +66 -0
  38. package/tests/skills-routing.test.mjs +7 -4
  39. package/tests/ui-tip-reload.test.mjs +70 -0
  40. package/tests/ui.test.mjs +450 -0
  41. package/tsconfig.json +1 -0
  42. package/eval/README.md +0 -72
  43. package/eval/permission-cases.json +0 -28
  44. package/eval/permissions.mjs +0 -103
  45. package/extensions/background-tasks.ts +0 -433
  46. package/extensions/background-worker.ts +0 -50
  47. package/extensions/glob.ts +0 -32
  48. package/extensions/mode.ts +0 -397
  49. package/lib/bash-approvals.ts +0 -113
  50. package/lib/bash-policy.ts +0 -164
  51. package/lib/mode-policy.ts +0 -174
  52. package/lib/path-policy.ts +0 -182
  53. package/lib/permission-classifier.ts +0 -128
  54. package/lib/permission-config.ts +0 -91
  55. package/lib/permission-denials.ts +0 -32
  56. package/lib/permission-intent.ts +0 -128
  57. package/lib/permission-taxonomy.ts +0 -15
  58. package/lib/task-broker.ts +0 -65
  59. package/lib/task-checkout.ts +0 -39
  60. package/lib/task-git.ts +0 -44
  61. package/lib/task-patch.ts +0 -106
  62. package/lib/task-permissions.ts +0 -51
  63. package/lib/task-report.ts +0 -62
  64. package/lib/task-worktree-policy.ts +0 -56
  65. package/skills/claude-api/SKILL.md +0 -572
  66. package/skills/claude-api/csharp/claude-api/README.md +0 -362
  67. package/skills/claude-api/csharp/claude-api/batches.md +0 -14
  68. package/skills/claude-api/csharp/claude-api/files-api.md +0 -25
  69. package/skills/claude-api/csharp/claude-api/streaming.md +0 -28
  70. package/skills/claude-api/csharp/claude-api/tool-use.md +0 -164
  71. package/skills/claude-api/curl/examples.md +0 -256
  72. package/skills/claude-api/curl/managed-agents.md +0 -371
  73. package/skills/claude-api/go/claude-api/README.md +0 -188
  74. package/skills/claude-api/go/claude-api/files-api.md +0 -23
  75. package/skills/claude-api/go/claude-api/streaming.md +0 -43
  76. package/skills/claude-api/go/claude-api/tool-use.md +0 -220
  77. package/skills/claude-api/go/managed-agents/README.md +0 -564
  78. package/skills/claude-api/java/claude-api/README.md +0 -238
  79. package/skills/claude-api/java/claude-api/files-api.md +0 -27
  80. package/skills/claude-api/java/claude-api/streaming.md +0 -24
  81. package/skills/claude-api/java/claude-api/tool-use.md +0 -228
  82. package/skills/claude-api/java/managed-agents/README.md +0 -443
  83. package/skills/claude-api/php/claude-api/README.md +0 -174
  84. package/skills/claude-api/php/claude-api/batches.md +0 -15
  85. package/skills/claude-api/php/claude-api/files-api.md +0 -13
  86. package/skills/claude-api/php/claude-api/streaming.md +0 -27
  87. package/skills/claude-api/php/claude-api/tool-use.md +0 -253
  88. package/skills/claude-api/php/managed-agents/README.md +0 -443
  89. package/skills/claude-api/python/claude-api/README.md +0 -565
  90. package/skills/claude-api/python/claude-api/batches.md +0 -198
  91. package/skills/claude-api/python/claude-api/files-api.md +0 -170
  92. package/skills/claude-api/python/claude-api/sdk-upgrade.md +0 -286
  93. package/skills/claude-api/python/claude-api/streaming.md +0 -179
  94. package/skills/claude-api/python/claude-api/tool-use.md +0 -627
  95. package/skills/claude-api/python/managed-agents/README.md +0 -335
  96. package/skills/claude-api/ruby/claude-api/README.md +0 -134
  97. package/skills/claude-api/ruby/claude-api/streaming.md +0 -16
  98. package/skills/claude-api/ruby/claude-api/tool-use.md +0 -41
  99. package/skills/claude-api/ruby/managed-agents/README.md +0 -394
  100. package/skills/claude-api/shared/admin-api.md +0 -179
  101. package/skills/claude-api/shared/agent-design.md +0 -101
  102. package/skills/claude-api/shared/anthropic-cli.md +0 -269
  103. package/skills/claude-api/shared/claude-platform-on-aws.md +0 -59
  104. package/skills/claude-api/shared/cost-optimization.md +0 -233
  105. package/skills/claude-api/shared/error-codes.md +0 -262
  106. package/skills/claude-api/shared/live-sources.md +0 -166
  107. package/skills/claude-api/shared/managed-agents-api-reference.md +0 -455
  108. package/skills/claude-api/shared/managed-agents-client-patterns.md +0 -220
  109. package/skills/claude-api/shared/managed-agents-core.md +0 -359
  110. package/skills/claude-api/shared/managed-agents-environments.md +0 -226
  111. package/skills/claude-api/shared/managed-agents-events.md +0 -290
  112. package/skills/claude-api/shared/managed-agents-memory.md +0 -201
  113. package/skills/claude-api/shared/managed-agents-multiagent.md +0 -260
  114. package/skills/claude-api/shared/managed-agents-onboarding.md +0 -82
  115. package/skills/claude-api/shared/managed-agents-outcomes.md +0 -108
  116. package/skills/claude-api/shared/managed-agents-overview.md +0 -77
  117. package/skills/claude-api/shared/managed-agents-scheduled-deployments.md +0 -156
  118. package/skills/claude-api/shared/managed-agents-self-hosted-sandboxes.md +0 -282
  119. package/skills/claude-api/shared/managed-agents-tools.md +0 -504
  120. package/skills/claude-api/shared/managed-agents-webhooks.md +0 -143
  121. package/skills/claude-api/shared/model-migration.md +0 -1872
  122. package/skills/claude-api/shared/models.md +0 -142
  123. package/skills/claude-api/shared/platform-availability.md +0 -53
  124. package/skills/claude-api/shared/prompt-audit.md +0 -223
  125. package/skills/claude-api/shared/prompt-caching.md +0 -292
  126. package/skills/claude-api/shared/token-counting.md +0 -56
  127. package/skills/claude-api/shared/tool-use-concepts.md +0 -526
  128. package/skills/claude-api/typescript/claude-api/README.md +0 -405
  129. package/skills/claude-api/typescript/claude-api/batches.md +0 -106
  130. package/skills/claude-api/typescript/claude-api/files-api.md +0 -98
  131. package/skills/claude-api/typescript/claude-api/streaming.md +0 -178
  132. package/skills/claude-api/typescript/claude-api/tool-use.md +0 -586
  133. package/skills/claude-api/typescript/managed-agents/README.md +0 -359
  134. package/tests/auto-permissions.test.mjs +0 -315
  135. package/tests/background-tasks.test.mjs +0 -27
  136. package/tests/background-worker.test.mjs +0 -60
  137. package/tests/bash-permissions.test.mjs +0 -276
  138. package/tests/glob.test.mjs +0 -31
  139. package/tests/mode.test.mjs +0 -62
  140. package/tests/permission-evaluation.test.mjs +0 -70
  141. package/tests/permission-foundation.test.mjs +0 -194
  142. package/tests/permission-policy.test.mjs +0 -158
  143. package/tests/runtime/README.md +0 -51
  144. package/tests/runtime/harness.mjs +0 -190
  145. package/tests/runtime/permissions.test.mjs +0 -192
  146. package/tests/runtime/tui.test.mjs +0 -60
  147. package/tests/task-integration.test.mjs +0 -324
  148. package/tests/task-permissions.test.mjs +0 -178
  149. 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
-