@preapexis/piexis 0.2.2 → 0.2.4

package/skills/claude-api/python/managed-agents/README.md

@@ -1,335 +0,0 @@
-# Managed Agents - Python
-
-> **Bindings not shown here:** This README covers the most common managed-agents flows for Python. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Python SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
-
-> **Agents are persistent - create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. **Recommended:** define agents and environments as version-controlled YAML applied with the `ant` CLI - see `shared/anthropic-cli.md` (its live-docs URL is in `shared/live-sources.md`). The CLI owns the control plane (create/update); your code owns the data plane (sessions with the stored ID). The examples below show in-code creation for when you must provision programmatically; in production the create call belongs in setup, not in the request path.
-
-## Installation
-
-```bash
-pip install anthropic
-```
-
-## Client Initialization
-
-```python
-import anthropic
-
-# Default - resolves credentials from the environment:
-# ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
-# Prefer this for local dev; don't hardcode a key.
-client = anthropic.Anthropic()
-
-# Explicit API key (only when you must inject a specific key)
-client = anthropic.Anthropic(api_key="your-api-key")
-```
-
----
-
-## Create an Environment
-
-```python
-environment = client.beta.environments.create(
-    name="my-dev-env",
-    config={
-        "type": "cloud",
-        "networking": {"type": "unrestricted"},
-    },
-)
-print(environment.id)  # env_...
-```
-
----
-
-## Create an Agent (required first step)
-
-> Warning: **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` - the session only takes `agent={"type": "agent", "id": agent.id}`.
-
-### Minimal
-
-```python
-# 1. Create the agent (reusable, versioned)
-agent = client.beta.agents.create(
-    name="Coding Assistant",
-    model="claude-opus-5",
-    tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}],
-)
-
-# 2. Start a session
-session = client.beta.sessions.create(
-    agent={"type": "agent", "id": agent.id, "version": agent.version},
-    environment_id=environment.id,
-)
-print(session.id, session.status)
-print(f"Trace: https://platform.claude.com/workspaces/default/sessions/{session.id}")  # swap 'default' for your workspace ID if the API key is not in the Default workspace
-```
-
-### With system prompt and custom tools
-
-```python
-import os
-
-agent = client.beta.agents.create(
-    name="Code Reviewer",
-    model="claude-opus-5",
-    system="You are a senior code reviewer.",
-    tools=[
-        {"type": "agent_toolset_20260401"},
-        {
-            "type": "custom",
-            "name": "run_tests",
-            "description": "Run the test suite",
-            "input_schema": {
-                "type": "object",
-                "properties": {
-                    "test_path": {"type": "string", "description": "Path to test file"}
-                },
-                "required": ["test_path"],
-            },
-        },
-    ],
-)
-
-session = client.beta.sessions.create(
-    agent={"type": "agent", "id": agent.id, "version": agent.version},
-    environment_id=environment.id,
-    title="Code review session",
-    resources=[
-        {
-            "type": "github_repository",
-            "url": "https://github.com/owner/repo",
-            "mount_path": "/workspace/repo",
-            "authorization_token": os.environ["GITHUB_TOKEN"],
-            "branch": "main",
-        }
-    ],
-)
-```
-
----
-
-## Send a User Message
-
-```python
-client.beta.sessions.events.send(
-    session_id=session.id,
-    events=[
-        {
-            "type": "user.message",
-            "content": [{"type": "text", "text": "Review the auth module"}],
-        }
-    ],
-)
-```
-
-> Tip: **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens - stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
-
----
-
-## Stream Events (SSE)
-
-```python
-import json
-
-# Stream-first: open stream, then send while stream is live
-with client.beta.sessions.events.stream(
-    session_id=session.id,
-) as stream:
-    client.beta.sessions.events.send(
-        session_id=session.id,
-        events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}],
-    )
-    for event in stream:
-        ...  # process events
-
-# Standalone stream iteration:
-with client.beta.sessions.events.stream(
-    session_id=session.id,
-) as stream:
-    for event in stream:
-        if event.type == "agent.message":
-            for block in event.content:
-                if block.type == "text":
-                    print(block.text, end="", flush=True)
-        elif event.type == "agent.custom_tool_use":
-            # Custom tool invocation - session is now idle
-            print(f"\nCustom tool call: {event.name}")
-            print(f"Input: {json.dumps(event.input)}")
-            # Send result back (see below)
-        elif event.type == "session.status_idle":
-            print("\n--- Agent idle ---")
-        elif event.type == "session.status_terminated":
-            print("\n--- Session terminated ---")
-            break
-```
-
----
-
-## Provide Custom Tool Result
-
-```python
-client.beta.sessions.events.send(
-    session_id=session.id,
-    events=[
-        {
-            "type": "user.custom_tool_result",
-            "custom_tool_use_id": "sevt_abc123",
-            "content": [{"type": "text", "text": "All 42 tests passed."}],
-        }
-    ],
-)
-```
-
----
-
-## Poll Events
-
-```python
-events = client.beta.sessions.events.list(
-    session_id=session.id,
-)
-for event in events.data:
-    print(f"{event.type}: {event.id}")
-```
-
-> Warning: **Prefer the SDK over raw `requests`/`httpx`.** If you hand-roll a poll loop, don't assume `timeout=(5, 60)` or `httpx.Timeout(120)` caps total call duration - both are **per-chunk** read timeouts (reset on every byte), so a trickling response can block forever. For a hard wall-clock deadline, track `time.monotonic()` at the loop level and bail explicitly, or wrap with `asyncio.wait_for()`. See [Receiving Events](../../shared/managed-agents-events.md#receiving-events).
-
----
-
-## Full Streaming Loop with Custom Tools
-
-```python
-import json
-
-
-def run_custom_tool(tool_name: str, tool_input: dict) -> str:
-    """Execute a custom tool and return the result."""
-    if tool_name == "run_tests":
-        # Your tool implementation here
-        return "All tests passed."
-    return f"Unknown tool: {tool_name}"
-
-
-def run_session(client, session_id: str):
-    """Stream events and handle custom tool calls."""
-    while True:
-        with client.beta.sessions.events.stream(
-            session_id=session_id,
-        ) as stream:
-            tool_calls = []
-            for event in stream:
-                if event.type == "agent.message":
-                    for block in event.content:
-                        if block.type == "text":
-                            print(block.text, end="", flush=True)
-                elif event.type == "agent.custom_tool_use":
-                    tool_calls.append(event)
-                elif event.type == "session.status_idle":
-                    break
-                elif event.type == "session.status_terminated":
-                    return
-
-        if not tool_calls:
-            break
-
-        # Process custom tool calls
-        results = []
-        for call in tool_calls:
-            result = run_custom_tool(call.name, call.input)
-            results.append({
-                "type": "user.custom_tool_result",
-                "custom_tool_use_id": call.id,
-                "content": [{"type": "text", "text": result}],
-            })
-
-        client.beta.sessions.events.send(
-            session_id=session_id,
-            events=results,
-        )
-```
-
----
-
-## Upload a File
-
-```python
-with open("data.csv", "rb") as f:
-    file = client.beta.files.upload(
-        file=f,
-    )
-
-# Use in a session
-session = client.beta.sessions.create(
-    agent={"type": "agent", "id": agent.id, "version": agent.version},
-    environment_id=environment.id,
-    resources=[{"type": "file", "file_id": file.id, "mount_path": "/workspace/data.csv"}],
-)
-```
-
----
-
-## List and Download Session Files
-
-List files the agent wrote to `/mnt/session/outputs/` during a session, then download them.
-
-```python
-# List files associated with a session
-files = client.beta.files.list(
-    scope_id=session.id,
-    betas=["managed-agents-2026-04-01"],
-)
-for f in files.data:
-    print(f.filename, f.size_bytes)
-    # Download each file and save to disk
-    file_content = client.beta.files.download(f.id)
-    file_content.write_to_file(f.filename)
-```
-
-> Tip: There's a brief indexing lag (~1-3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if the list is empty.
-
----
-
-## Session Management
-
-```python
-# Get session details
-session = client.beta.sessions.retrieve(session_id="sesn_011CZxAbc123Def456")
-print(session.status, session.usage)
-
-# List sessions
-sessions = client.beta.sessions.list()
-
-# Delete a session
-client.beta.sessions.delete(session_id="sesn_011CZxAbc123Def456")
-
-# Archive a session
-client.beta.sessions.archive(session_id="sesn_011CZxAbc123Def456")
-```
-
----
-
-## MCP Server Integration
-
-```python
-# Agent declares MCP server (no auth here - auth goes in a vault)
-agent = client.beta.agents.create(
-    name="MCP Agent",
-    model="claude-opus-5",
-    mcp_servers=[
-        {"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"},
-    ],
-    tools=[
-        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
-        {"type": "mcp_toolset", "mcp_server_name": "my-tools"},
-    ],
-)
-
-# Session attaches vault(s) containing credentials for those MCP server URLs
-session = client.beta.sessions.create(
-    agent=agent.id,
-    environment_id=environment.id,
-    vault_ids=[vault.id],
-)
-```
-
-See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.

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

@@ -1,134 +0,0 @@
-# Claude API - Ruby
-
-> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby.
-
-## Installation
-
-```bash
-gem install anthropic
-```
-
-## Client Initialization
-
-```ruby
-require "anthropic"
-
-# Default (uses ANTHROPIC_API_KEY env var)
-client = Anthropic::Client.new
-
-# Explicit API key
-client = Anthropic::Client.new(api_key: "your-api-key")
-```
-
----
-
-## Basic Message Request
-
-```ruby
-message = client.messages.create(
-  model: :"claude-opus-5",
-  max_tokens: 16000,
-  messages: [
-    { role: "user", content: "What is the capital of France?" }
-  ]
-)
-# content is an array of polymorphic block objects (TextBlock, ThinkingBlock,
-# ToolUseBlock, ...). .type is a Symbol - compare with :text, not "text".
-# .text raises NoMethodError on non-TextBlock entries.
-message.content.each do |block|
-  puts block.text if block.type == :text
-end
-```
-
----
-
-## Extended Thinking
-
-> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` 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 - omitting `thinking:` runs adaptive (`{ type: "adaptive" }` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{ type: "disabled" }` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400.
-> **Older models:** Use `thinking: { type: "enabled", budget_tokens: N }` (must be < `max_tokens`, min 1024).
-
-```ruby
-message = client.messages.create(
-  model: :"claude-opus-5",
-  max_tokens: 16000,
-  thinking: { type: "adaptive" },
-  messages: [{ role: "user", content: "Solve: 27 * 453" }]
-)
-
-message.content.each do |block|
-  case block.type
-  when :thinking then puts "Thinking: #{block.thinking}"
-  when :text then puts "Response: #{block.text}"
-  end
-end
-```
-
----
-
-## Prompt Caching
-
-`system_:` (trailing underscore - avoids shadowing `Kernel#system`) takes an array of text blocks; set `cache_control` on the last block. Plain hashes work via the `OrHash` type alias. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
-
-```ruby
-message = client.messages.create(
-  model: :"claude-opus-5",
-  max_tokens: 16000,
-  system_: [
-    { type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } }
-  ],
-  messages: [{ role: "user", content: "Summarize the key points" }]
-)
-```
-
-For 1-hour TTL: `cache_control: { type: "ephemeral", ttl: "1h" }`. There's also a top-level `cache_control:` on `messages.create` that auto-places on the last cacheable block.
-
-Verify hits via `message.usage.cache_creation_input_tokens` / `message.usage.cache_read_input_tokens`.
-
----
-
-## Stop Details
-
-When `stop_reason` is `:refusal`, the response includes structured `stop_details`:
-
-```ruby
-if message.stop_reason == :refusal && message.stop_details
-  puts "Category: #{message.stop_details.category}"     # e.g. :cyber, :bio, :reasoning_extraction, :frontier_llm, or nil - see docs for the full set
-  puts "Explanation: #{message.stop_details.explanation}"
-end
-```
-
-**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`, `fallbacks: [{model: "claude-opus-4-8"}]` on the beta messages call) by default. The exact Ruby binding (and the client-side middleware for providers without server-side support) is not documented here - WebFetch the Ruby 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.
-
----
-
-## Beta Features
-
-`betas:` is only valid on `client.beta.messages.create`, not the non-beta path.
-
-### Task budgets
-
-```ruby
-response = client.beta.messages.create(
-  model: :"claude-opus-5",
-  max_tokens: 16000,
-  output_config: { task_budget: { type: :tokens, total: 64_000 } },
-  tools: [...],
-  messages: [...],
-  betas: ["task-budgets-2026-03-13"]
-)
-```
-
----
-
-## Error Type
-
-`APIStatusError` exposes a `.type` field for programmatic error classification:
-
-```ruby
-begin
-  client.messages.create(...)
-rescue Anthropic::Errors::APIStatusError => e
-  puts e.type  # :rate_limit_error, :overloaded_error, etc.
-end
-```

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

@@ -1,16 +0,0 @@
-# Streaming - Ruby
-
-## Streaming
-
-```ruby
-stream = client.messages.stream(
-  model: :"claude-opus-5",
-  max_tokens: 64000,
-  messages: [{ role: "user", content: "Write a haiku" }]
-)
-
-stream.text.each { |text| print(text) }
-```
-
----
-

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

@@ -1,41 +0,0 @@
-# Tool Use - Ruby
-
-For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
-
-## Tool Use
-
-The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.
-
-### Tool Runner (Beta)
-
-```ruby
-class GetWeatherInput < Anthropic::BaseModel
-  required :location, String, doc: "City and state, e.g. San Francisco, CA"
-end
-
-class GetWeather < Anthropic::BaseTool
-  doc "Get the current weather for a location"
-
-  input_schema GetWeatherInput
-
-  def call(input)
-    "The weather in #{input.location} is sunny and 72°F."
-  end
-end
-
-client.beta.messages.tool_runner(
-  model: :"claude-opus-5",
-  max_tokens: 16000,
-  tools: [GetWeather.new],
-  messages: [{ role: "user", content: "What's the weather in San Francisco?" }]
-).each_message do |message|
-  puts message.content
-end
-```
-
-### Manual Loop
-
-See the [shared tool use concepts](../../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern.
-
----
-