@preapexis/piexis 0.1.2 → 0.2.4

package/skills/claude-api/go/claude-api/README.md

@@ -1,188 +0,0 @@
-# Claude API - Go
-
-> **Note:** The Go SDK supports the Claude API and beta tool use with `BetaToolRunner`. Agent SDK is not yet available for Go.
-
-## Installation
-
-```bash
-go get github.com/anthropics/anthropic-sdk-go
-```
-
-## Client Initialization
-
-```go
-import (
-    "github.com/anthropics/anthropic-sdk-go"
-    "github.com/anthropics/anthropic-sdk-go/option"
-)
-
-// Default (uses ANTHROPIC_API_KEY env var)
-client := anthropic.NewClient()
-
-// Explicit API key
-client := anthropic.NewClient(
-    option.WithAPIKey("your-api-key"),
-)
-```
-
----
-
-## Model Constants
-
-The Go SDK provides typed model constants: `anthropic.ModelClaudeFable5`, `anthropic.ModelClaudeOpus4_8`, `anthropic.ModelClaudeOpus4_7`, `anthropic.ModelClaudeSonnet4_6`, `anthropic.ModelClaudeHaiku4_5_20251001`. Default to Claude Opus 5 unless the user specifies otherwise; if they ask for Fable or the most powerful model, use `anthropic.ModelClaudeFable5` (see `shared/models.md` for the full resolution table).
-
-`anthropic.Model` is an alias for `string`, so a model with no typed constant yet - including Claude Opus 5 - is passed as the plain id: `Model: "claude-opus-5"`. Check the SDK release notes for a typed `Claude Opus 5` constant before assuming one exists.
-
----
-
-## Basic Message Request
-
-```go
-response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
-    Model:     "claude-opus-5",
-    MaxTokens: 16000,
-    Messages: []anthropic.MessageParam{
-        anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")),
-    },
-})
-if err != nil {
-    log.Fatal(err)
-}
-for _, block := range response.Content {
-    switch variant := block.AsAny().(type) {
-    case anthropic.TextBlock:
-        fmt.Println(variant.Text)
-    }
-}
-```
-
----
-
-## Thinking
-
-Enable Claude's internal reasoning by setting `Thinking` in `MessageNewParams`. The response will contain `ThinkingBlock` content before the final `TextBlock`.
-
-**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. Combine with the `effort` parameter for cost-quality control.
-
-Derived from `anthropic-sdk-go/message.go` (`ThinkingConfigParamUnion`, `ThinkingConfigAdaptiveParam`).
-
-```go
-// There is no ThinkingConfigParamOfAdaptive helper - construct the union
-// struct-literal directly and take the address of the variant.
-adaptive := anthropic.ThinkingConfigAdaptiveParam{}
-params := anthropic.MessageNewParams{
-    Model:     anthropic.ModelClaudeSonnet4_6,
-    MaxTokens: 16000,
-    Thinking:  anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive},
-    Messages: []anthropic.MessageParam{
-        anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")),
-    },
-}
-
-resp, err := client.Messages.New(context.Background(), params)
-if err != nil {
-    log.Fatal(err)
-}
-
-// ThinkingBlock(s) precede TextBlock in content
-for _, block := range resp.Content {
-    switch b := block.AsAny().(type) {
-    case anthropic.ThinkingBlock:
-        fmt.Println("[thinking]", b.Thinking)
-    case anthropic.TextBlock:
-        fmt.Println(b.Text)
-    }
-}
-```
-
-> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking (above). `ThinkingConfigParamOfEnabled(budgetTokens)` 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.
-> **Claude Opus 5:** thinking is on by default - leaving `Thinking` unset runs adaptive (the adaptive union is equivalent), unlike Opus 4.8/4.7 where leaving it unset meant no thinking.
-> **Older models:** Use `anthropic.ThinkingConfigParamOfEnabled(N)` (budget must be < `MaxTokens`, min 1024).
-
-To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`. On Claude Opus 5 that is accepted only at effort `high` or lower - pairing it with `xhigh`/`max` returns a 400.
-
----
-
-## Prompt Caching
-
-`System` is `[]TextBlockParam`; set `CacheControl` on the last block to cache tools + system together. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
-
-```go
-System: []anthropic.TextBlockParam{{
-    Text:         longSystemPrompt,
-    CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL
-}},
-```
-
-For 1-hour TTL: `anthropic.CacheControlEphemeralParam{TTL: anthropic.CacheControlEphemeralTTLTTL1h}`. There's also a top-level `CacheControl` on `MessageNewParams` that auto-places on the last cacheable block.
-
-Verify hits via `resp.Usage.CacheCreationInputTokens` / `resp.Usage.CacheReadInputTokens`.
-
----
-
-## Stop Details
-
-When `StopReason` is `anthropic.StopReasonRefusal`, the response includes structured `StopDetails`:
-
-```go
-if resp.StopReason == anthropic.StopReasonRefusal {
-    fmt.Println("Category:", resp.StopDetails.Category)     // e.g. "cyber", "bio", "reasoning_extraction", "frontier_llm", or "" - see docs for the full set
-    fmt.Println("Explanation:", resp.StopDetails.Explanation)
-}
-```
-
-**Refusal fallbacks (Claude Fable 5.1) - opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. In `claude-fable-5-1` code, include `Fallbacks: []anthropic.BetaFallbackParam{{Model: "claude-opus-4-8"}}` plus the `anthropic.AnthropicBetaServerSideFallback2026_06_01` beta on `client.Beta.Messages.New` by default - a policy decline is re-served by the fallback model inside the same call. Not available on Amazon Bedrock, Vertex AI, or Microsoft Foundry - register the client-side middleware there: `option.WithMiddleware(betafallback.BetaRefusalFallbackMiddleware(...))` from `lib/betafallback`, with per-conversation state via `betafallback.WithBetaFallbackState(&betafallback.BetaFallbackState{})`. Full semantics (billing, sticky routing, streaming) and a runnable example: `shared/model-migration.md` -> Migrating to Claude Fable 5.1 -> `refusal` stop reason, and the Go SDK repo's `examples/` (WebFetch via `shared/live-sources.md`).
-
----
-
-## PDF / Document Input
-
-`NewDocumentBlock` generic helper accepts any source type. `MediaType`/`Type` are auto-set.
-
-```go
-b64 := base64.StdEncoding.EncodeToString(pdfBytes)
-
-msg := anthropic.NewUserMessage(
-    anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}),
-    anthropic.NewTextBlock("Summarize this document"),
-)
-```
-
-Other sources: `URLPDFSourceParam{URL: "https://..."}`, `PlainTextSourceParam{Data: "..."}`.
-
----
-
-## Context Editing / Compaction (Beta)
-
-Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. There is no `NewBetaAssistantMessage` - use `.ToParam()` for the round-trip.
-
-```go
-params := anthropic.BetaMessageNewParams{
-    Model:     "claude-opus-5",  // also supported: ModelClaudeOpus4_8, ModelClaudeSonnet4_6
-    MaxTokens: 16000,
-    Betas:     []anthropic.AnthropicBeta{"compact-2026-01-12"},
-    ContextManagement: anthropic.BetaContextManagementConfigParam{
-        Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
-            {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
-        },
-    },
-    Messages: []anthropic.BetaMessageParam{ /* ... */ },
-}
-
-resp, err := client.Beta.Messages.New(ctx, params)
-if err != nil {
-    log.Fatal(err)
-}
-
-// Round-trip: append response to history via .ToParam()
-params.Messages = append(params.Messages, resp.ToParam())
-
-// Read compaction blocks from the response
-for _, block := range resp.Content {
-    if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok {
-        fmt.Println("compaction summary:", c.Content)
-    }
-}
-```
-
-Other edit types: `BetaClearToolUses20250919EditParam`, `BetaClearThinking20251015EditParam` - these need `Betas: []anthropic.AnthropicBeta{"context-management-2025-06-27"}`, not `compact-2026-01-12`.

package/skills/claude-api/go/claude-api/files-api.md

@@ -1,23 +0,0 @@
-# Files API - Go
-
-## Files API
-
-> **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.
-
-Under `client.Beta.Files`. Method is **`Upload`** (NOT `New`/`Create`), params struct is `BetaFileUploadParams`. The `File` field takes an `io.Reader`; use `anthropic.File()` to attach a filename + content-type for the multipart encoding.
-
-```go
-f, _ := os.Open("./upload_me.txt")
-defer f.Close()
-
-meta, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
-    File:  anthropic.File(f, "upload_me.txt", "text/plain"),
-    Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
-})
-// meta.ID is the file_id to reference in subsequent message requests
-```
-
-Other `Beta.Files` methods: `List`, `Delete`, `Download`, `GetMetadata`.
-
----
-

package/skills/claude-api/go/claude-api/streaming.md

@@ -1,43 +0,0 @@
-# Streaming - Go
-
-## Streaming
-
-```go
-stream := client.Messages.NewStreaming(context.Background(), anthropic.MessageNewParams{
-    Model:     anthropic.ModelClaudeOpus4_8,
-    MaxTokens: 64000,
-    Messages: []anthropic.MessageParam{
-        anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")),
-    },
-})
-
-for stream.Next() {
-    event := stream.Current()
-    switch eventVariant := event.AsAny().(type) {
-    case anthropic.ContentBlockDeltaEvent:
-        switch deltaVariant := eventVariant.Delta.AsAny().(type) {
-        case anthropic.TextDelta:
-            fmt.Print(deltaVariant.Text)
-        }
-    }
-}
-if err := stream.Err(); err != nil {
-    log.Fatal(err)
-}
-```
-
-**Accumulating the final message** (there is no `GetFinalMessage()` on the stream):
-
-```go
-stream := client.Messages.NewStreaming(ctx, params)
-message := anthropic.Message{}
-for stream.Next() {
-    message.Accumulate(stream.Current())
-}
-if err := stream.Err(); err != nil { log.Fatal(err) }
-// message.Content now has the complete response
-```
-
-
----
-

package/skills/claude-api/go/claude-api/tool-use.md

@@ -1,220 +0,0 @@
-# Tool Use - Go
-
-For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
-
-## Tool Use
-
-### Tool Runner (Beta - Recommended)
-
-**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package.
-
-```go
-import (
-    "context"
-    "fmt"
-    "log"
-
-    "github.com/anthropics/anthropic-sdk-go"
-    "github.com/anthropics/anthropic-sdk-go/toolrunner"
-)
-
-// Define tool input with jsonschema tags for automatic schema generation
-type GetWeatherInput struct {
-    City string `json:"city" jsonschema:"required,description=The city name"`
-}
-
-// Create a tool with automatic schema generation from struct tags
-weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
-    "get_weather",
-    "Get current weather for a city",
-    func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
-        return anthropic.BetaToolResultBlockParamContentUnion{
-            OfText: &anthropic.BetaTextBlockParam{
-                Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City),
-            },
-        }, nil
-    },
-)
-if err != nil {
-    log.Fatal(err)
-}
-
-// Create a tool runner that handles the conversation loop automatically
-runner := client.Beta.Messages.NewToolRunner(
-    []anthropic.BetaTool{weatherTool},
-    anthropic.BetaToolRunnerParams{
-        BetaMessageNewParams: anthropic.BetaMessageNewParams{
-            Model:     anthropic.ModelClaudeOpus4_8,
-            MaxTokens: 16000,
-            Messages: []anthropic.BetaMessageParam{
-                anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")),
-            },
-        },
-        MaxIterations: 5,
-    },
-)
-
-// Run until Claude produces a final response
-message, err := runner.RunToCompletion(context.Background())
-if err != nil {
-    log.Fatal(err)
-}
-
-// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion.
-// Narrow via AsAny() switch - note the Beta-namespace types (BetaTextBlock,
-// not TextBlock):
-for _, block := range message.Content {
-    switch block := block.AsAny().(type) {
-    case anthropic.BetaTextBlock:
-        fmt.Println(block.Text)
-    }
-}
-```
-
-**Key features of the Go tool runner:**
-
-- Automatic schema generation from Go structs via `jsonschema` tags
-- `RunToCompletion()` for simple one-shot usage
-- `All()` iterator for processing each message in the conversation
-- `NextMessage()` for step-by-step iteration
-- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()`
-
-### Manual Loop
-
-Prefer the tool runner above. For interception, validation, logging, or human-in-the-loop approval, gate inside the tool's run function or step the runner with `NextMessage()`/`All()` and inspect each message (the runner's public `Params` field lets you adjust the next request) - a manual loop is not required. Drop to a manual loop only when you need control the runner does not expose: define tools with `ToolParam`, check `StopReason`, execute tools yourself, and feed `tool_result` blocks back.
-
-Derived from `anthropic-sdk-go/examples/tools/main.go`.
-
-```go
-package main
-
-import (
-    "context"
-    "encoding/json"
-    "fmt"
-    "log"
-
-    "github.com/anthropics/anthropic-sdk-go"
-)
-
-func main() {
-    client := anthropic.NewClient()
-
-    // 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed.
-    addTool := anthropic.ToolParam{
-        Name:        "add",
-        Description: anthropic.String("Add two integers"),
-        InputSchema: anthropic.ToolInputSchemaParam{
-            Properties: map[string]any{
-                "a": map[string]any{"type": "integer"},
-                "b": map[string]any{"type": "integer"},
-            },
-        },
-    }
-    // ToolParam must be wrapped in ToolUnionParam for the Tools slice
-    tools := []anthropic.ToolUnionParam{{OfTool: &addTool}}
-
-    messages := []anthropic.MessageParam{
-        anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")),
-    }
-
-    for {
-        resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
-            Model:     anthropic.ModelClaudeSonnet4_6,
-            MaxTokens: 16000,
-            Messages:  messages,
-            Tools:     tools,
-        })
-        if err != nil {
-            log.Fatal(err)
-        }
-
-        // 2. Append the assistant response to history BEFORE processing tool calls.
-        //    resp.ToParam() converts Message -> MessageParam in one call.
-        messages = append(messages, resp.ToParam())
-
-        // 3. Walk content blocks. ContentBlockUnion is a flattened struct;
-        //    use block.AsAny().(type) to switch on the actual variant.
-        toolResults := []anthropic.ContentBlockParamUnion{}
-        for _, block := range resp.Content {
-            switch variant := block.AsAny().(type) {
-            case anthropic.TextBlock:
-                fmt.Println(variant.Text)
-            case anthropic.ToolUseBlock:
-                // 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the
-                //    raw JSON - block.Input is json.RawMessage, not the parsed value.
-                var in struct {
-                    A int `json:"a"`
-                    B int `json:"b"`
-                }
-                if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil {
-                    log.Fatal(err)
-                }
-                result := fmt.Sprintf("%d", in.A+in.B)
-                // 5. NewToolResultBlock(toolUseID, content, isError) builds the
-                //    ContentBlockParamUnion for you. block.ID is the tool_use_id.
-                toolResults = append(toolResults,
-                    anthropic.NewToolResultBlock(block.ID, result, false))
-            }
-        }
-
-        // 6. Exit when Claude stops asking for tools
-        if resp.StopReason != anthropic.StopReasonToolUse {
-            break
-        }
-
-        // 7. Tool results go in a user message (variadic: all results in one turn)
-        messages = append(messages, anthropic.NewUserMessage(toolResults...))
-    }
-}
-```
-
-**Key API surface:**
-
-| Symbol | Purpose |
-|---|---|
-| `resp.ToParam()` | Convert `Message` response -> `MessageParam` for history |
-| `block.AsAny().(type)` | Type-switch on `ContentBlockUnion` variants |
-| `variant.JSON.Input.Raw()` | Raw JSON string of tool input (for `json.Unmarshal`) |
-| `anthropic.NewToolResultBlock(id, content, isError)` | Build `tool_result` block |
-| `anthropic.NewUserMessage(blocks...)` | Wrap tool results as a user turn |
-| `anthropic.StopReasonToolUse` | `StopReason` constant to check loop termination |
-| `anthropic.ToolUnionParam{OfTool: &t}` | Wrap `ToolParam` in the union for `Tools:` |
-
----
-
-## Anthropic-Defined Tools
-
-Version-suffixed struct names with `Param` suffix. `Name`/`Type` are `constant.*` types - zero value marshals correctly, so `{}` works. Wrap in `ToolUnionParam` with the matching `Of*` field. 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`).
-
-```go
-Tools: []anthropic.ToolUnionParam{
-    {OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}},
-    {OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
-    {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
-    {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
-},
-```
-
-Also available: `WebFetchTool20260209Param`, `ToolSearchToolBm25_20251119Param`, `ToolSearchToolRegex20251119Param`. For the advisor and memory tools, use `BetaAdvisorTool20260301Param` / `BetaMemoryTool20250818Param` in the beta namespace on `client.Beta.Messages.New`.
-
-### Advisor tool (beta)
-
-Server-side - no tool_result round-trip. The advisor model must be >= the executor (top-level) model; invalid pairs return 400.
-
-```go
-response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
-    Model:     anthropic.ModelClaudeSonnet4_6,
-    MaxTokens: 4096,
-    Tools: []anthropic.BetaToolUnionParam{
-        {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
-            Model: anthropic.ModelClaudeOpus4_8,
-        }},
-    },
-    Messages: []anthropic.BetaMessageParam{ /* ... */ },
-    Betas:    []anthropic.AnthropicBeta{anthropic.AnthropicBetaAdvisorTool2026_03_01},
-})
-```
-
----
-