tada-core 0.2.0__tar.gz

tada_core-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest tests/
+      - run: uv run ruff check tada_core tests scripts

tada_core-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync
+      - run: uv run pytest tests/
+      - run: uv run ruff check tada_core tests scripts
+      - run: uv run python scripts/contract_sdk_install.py
+      - run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

tada_core-0.2.0/.gitignore

@@ -0,0 +1,29 @@
+.venv/
+__pycache__/
+*.pyc
+.DS_Store
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.worktrees/
+.claude/
+internal-docs/
+docs/superpowers/
+docs/architecture/tada-agent-*
+docs/architecture/claw-code-*
+docs/architecture/hermes-agent-*
+docs/architecture/pi-*
+docs/architecture/claude-code-*
+docs/reference/pi-coding-agent-post.md
+plans/
+agent-apps/.local/
+agent-apps/agent-1/.local/
+agent-apps/agent-1/frontend/node_modules/
+agent-apps/agent-1/frontend/dist/
+agent-apps/agent-studio/backend/.config.json
+agent-apps/agent-studio/frontend/node_modules/
+agent-apps/agent-studio/frontend/.next/
+agent-apps/shared/sandbox/runtime/*
+!agent-apps/shared/sandbox/runtime/.gitkeep

tada_core-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

tada_core-0.2.0/AGENTS.md

@@ -0,0 +1,297 @@
+# tada-core - AGENTS.md
+
+AI-readable reference for the `tada-core` Python SDK.
+
+## SDK Identity
+
+- **Package**: `tada_core` (`pip install tada-core`)
+- **Python**: >=3.10
+- **Core deps**: `httpx>=0.27`, `pydantic>=2.0`, `typing-extensions>=4.8`
+- **Role**: multi-protocol agent runtime SDK: unified Message/Event contracts, adapter registry, streaming events, tool dispatch, hook/permission/compaction/budget extension points, and serializable session state
+- **NOT**: a product shell, a channel router, a long-term memory service, a tool middleware framework, routing/fallback/quota/billing, or OAuth
+- **Model routing**: handled by `token-router`; `tada-core` selects protocol adapters via `ModelSpec.api` (`anthropic-messages`, `openai-responses`, `openai-completions`, `google-generative-ai`, `bedrock-converse-stream`)
+
+## Public API
+
+The current public surface is exactly the names exported from `tada_core.__all__`:
+
+```python
+from tada_core import (
+    AgentLoop,
+    AnthropicModelClient,
+    BudgetLimits,
+    ChainedToolExecutor,
+    CharacterTokenEstimator,
+    CompactionConfig,
+    CompactionMode,
+    CompactionStrategy,
+    ContentNormalizerConfig,
+    ContentBlock,
+    ConversationMessage,
+    Event,
+    MessageRole,
+    ModelSpec,
+    ModelSummaryCompaction,
+    NeverCompact,
+    SessionState,
+    StopReason,
+    StructuredSummaryCompaction,
+    TokenEstimator,
+    ToolResult,
+    ToolResultPruningConfig,
+    TruncateCompaction,
+    RetryPolicy,
+    RetryingModelClient,
+    build_model_client,
+    normalize_messages,
+    __version__,
+)
+```
+
+| Name | Kind | Purpose |
+|------|------|---------|
+| `AgentLoop` | class | Main agent runtime loop; calls model, tools, hooks, permissions, and compaction |
+| `AnthropicModelClient` | class | Anthropic Messages API adapter for direct Anthropic, token-router, LiteLLM Anthropic mode, and similar proxies |
+| `BudgetLimits` | Pydantic model | Provider-neutral runtime limits for tokens, iterations, and tool calls |
+| `CharacterTokenEstimator` | class | Dependency-free fallback token estimator |
+| `ChainedToolExecutor` | class | Wraps a `ToolExecutor` with ordered async middleware |
+| `CompactionConfig` | Pydantic model | Runtime compaction configuration, including thresholds, protected head/tail, and tool result pruning |
+| `CompactionMode` | enum | Built-in compaction modes: `auto`, `disabled`, `hook_only` |
+| `CompactionStrategy` | ABC | Contract for custom conversation compaction |
+| `ContentNormalizerConfig` | Pydantic model | Optional multimodal normalization config |
+| `ContentBlock` | Pydantic model | Text, thinking, tool, tool result, image, and file block inside a message |
+| `ConversationMessage` | Pydantic model | Provider-agnostic transcript message |
+| `Event` | type alias | Discriminated union of runtime events |
+| `MessageRole` | enum | `user`, `assistant`, or `tool` |
+| `ModelSpec` | Pydantic model | Lightweight model/protocol capability descriptor (not a full catalog) |
+| `ModelSummaryCompaction` | class | LLM-backed compaction strategy |
+| `NeverCompact` | class | Default no-op compaction strategy |
+| `SessionState` | Pydantic model | Serializable conversation state and cumulative usage |
+| `StopReason` | enum | Normalized assistant message stop reason |
+| `StructuredSummaryCompaction` | class | Default production compaction strategy with structured summary, tool result pruning, source ids, and token-aware tail selection |
+| `TokenEstimator` | protocol | Provider-neutral token estimation contract |
+| `ToolResult` | dataclass | Structured tool result with optional multimodal blocks |
+| `ToolResultPruningConfig` | Pydantic model | Configures active pruning of oversized old `tool_result` blocks and placeholder/manifest behavior |
+| `TruncateCompaction` | class | Keeps the most recent N messages |
+| `RetryPolicy` | Pydantic model | Retry policy for `RetryingModelClient` |
+| `RetryingModelClient` | class | Model client wrapper that retries pre-stream transient errors |
+| `build_model_client` | function | Build a registered `ModelClient` from `ModelSpec` |
+| `normalize_messages` | function | Optional content normalizer for local paths, URL images, MIME aliases, and image sizing |
+| `__version__` | str | Package version |
+
+Adding a new public export requires a minor version bump. Adding optional fields to existing Pydantic models is patch-compatible during 0.x, but persisted `SessionState` JSON is not guaranteed to be readable by older package versions.
+
+## Minimal Integration
+
+```python
+import asyncio
+
+from tada_core import AgentLoop, AnthropicModelClient, SessionState
+
+loop = AgentLoop(
+    AnthropicModelClient(
+        api_key="token-router-key",
+        model="claude-sonnet-4-6",
+        base_url="http://localhost:8787",
+        cache_retention="short",
+    ),
+    system_prompt=["You are a concise assistant."],
+)
+state = SessionState()
+
+async def main() -> None:
+    async for event in loop.run_turn(state, "hello"):
+        if event.type == "text_delta":
+            print(event.text, end="", flush=True)
+        elif event.type == "error":
+            raise RuntimeError(f"{event.code}: {event.message}")
+
+asyncio.run(main())
+```
+
+`state` is mutated in place. Persist it with `state.model_dump_json()` and restore it with `SessionState.model_validate_json(...)`.
+
+## Message Model
+
+```python
+from tada_core import ContentBlock, ConversationMessage, MessageRole, SessionState
+
+state = SessionState(
+    messages=[
+        ConversationMessage(
+            role=MessageRole.USER,
+            content=[
+                ContentBlock(
+                    type="image",
+                    source="base64",
+                    mime_type="image/png",
+                    data="...",
+                ),
+                ContentBlock(type="text", text="Describe this image."),
+            ],
+        )
+    ]
+)
+```
+
+Known `ContentBlock.type` values:
+
+| Type | Key fields |
+|------|------------|
+| `text` | `text` |
+| `thinking` | `thinking`, optional `signature` |
+| `tool_use` | `tool_use_id`, `tool_name`, `tool_input` |
+| `tool_result` | `tool_use_id`, `tool_name`, `tool_result`, `is_error` |
+| `image` | `source`, `mime_type`, `data` or `url` |
+| `file` | `source`, `mime_type`, `data` or `url`, optional `name` |
+
+`type` remains a free-form string for forward compatibility, but known multimodal block types validate required payload fields.
+
+## Event Types
+
+Pattern-match on `event.type`.
+
+| `.type` | Class | Key fields |
+|---------|-------|------------|
+| `turn_start` | `TurnStartEvent` | `turn_index` |
+| `turn_end` | `TurnEndEvent` | `iterations_used`, `completed` |
+| `text_start` | `TextStart` | no payload |
+| `text_delta` | `TextDelta` | `text` |
+| `text_end` | `TextEnd` | `text` |
+| `thinking_start` | `ThinkingStart` | no payload |
+| `thinking_delta` | `ThinkingDelta` | `text` |
+| `thinking_end` | `ThinkingEnd` | `text` |
+| `tool_input_delta` | `ToolInputDelta` | `tool_use_id`, `tool_name`, `delta` |
+| `tool_use` | `ToolUseRequest` | `tool_use_id`, `tool_name`, `input_json` |
+| `tool_result` | `ToolResultEvent` | `tool_use_id`, `tool_name`, `output`, `is_error` |
+| `tool_progress` | `ToolProgressEvent` | `tool_use_id`, `tool_name`, `update` |
+| `usage` | `UsageEvent` | `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens` |
+| `message_stop` | `MessageStop` | optional `stop_reason` |
+| `permission` | `PermissionEvent` | `tool_name`, `allowed`, `reason` |
+| `hook` | `HookEvent` | `hook_name`, `phase`, `messages` |
+| `compaction` | `CompactionEvent` | `strategy`, `removed_message_count`, `summary`, `compacted_message_ids`, `pruned_tool_results_count`, `fallback_used` |
+| `error` | `ErrorEvent` | `message`, `code` |
+| `unsupported` | `UnsupportedEvent` | `feature`, `detail` |
+| `loop_exit` | `LoopExitEvent` | `tool_name`, `reason` |
+| `steering` | `SteeringEvent` | `tool_name`, `message_count`, `skipped_tools` |
+
+Important ordering guarantees:
+
+1. `tool_use` is emitted before `permission`, which is emitted before `tool_result` for the same tool call.
+2. `tool_progress` events appear before the final `tool_result` for a tool.
+3. `usage` events update `SessionState.usage` before they are yielded.
+
+## AnthropicModelClient
+
+`AnthropicModelClient` serializes `ConversationMessage` into Anthropic Messages API wire format and sends `POST /v1/messages`.
+
+```python
+AnthropicModelClient(
+    api_key="...",
+    model="claude-sonnet-4-6",
+    base_url="http://localhost:8787",
+    streaming=True,
+    max_tokens=8192,
+    extra_headers={},
+    cache_retention="short",  # "none" | "short" | "long"
+)
+```
+
+Cache behavior:
+
+- `cache_retention="none"`: no `cache_control` markers.
+- `cache_retention="short"`: block-level `{"type": "ephemeral"}` markers.
+- `cache_retention="long"`: emits `ttl="1h"` only for official `api.anthropic.com`; other base URLs automatically use short retention for proxy compatibility.
+- Markers are always attached to content blocks, never as a top-level SDK parameter.
+- Up to four breakpoints are used: system, tools, previous user turn, current user turn.
+
+## Tools
+
+```python
+from tada_core.contracts.tools import InMemoryToolExecutor, ToolDefinition
+
+executor = InMemoryToolExecutor()
+executor.register(
+    ToolDefinition(
+        name="echo",
+        description="Return input unchanged",
+        parameters_schema={"type": "object"},
+    ),
+    lambda input_json: input_json,
+)
+loop.set_tool_executor(executor)
+```
+
+Tool functions receive and return JSON strings. Tool middleware, platform-specific auth, file upload/download, and channel rendering stay in the host application.
+
+## Permissions
+
+```python
+from tada_core.contracts.permissions import DenyListPolicy
+
+loop.set_permission_policy(DenyListPolicy(denied={"shell", "rm"}))
+```
+
+Custom policies implement `PermissionPolicy.authorize(...)`.
+
+## Hooks
+
+Hooks are the extension point for host-side behavior such as hint injection, tracing, memory retrieval, tool input rewriting, and ask-user style loop exits.
+
+Supported phases include:
+
+- `OnSessionStart`
+- `OnTurnStart`
+- `PreLlmCall`
+- `PostLlmCall`
+- `PreToolUse`
+- `PostToolUse`
+- `PostToolUseFailure`
+- `OnTurnEnd`
+
+Use `FunctionHookRunner` for simple callback composition or implement `HookRunner` directly.
+
+## Compaction
+
+```python
+from tada_core import TruncateCompaction
+
+loop.set_compaction_strategy(TruncateCompaction(max_messages=40))
+```
+
+Built-ins:
+
+- `NeverCompact`
+- `TruncateCompaction`
+- `ModelSummaryCompaction`
+- `StructuredSummaryCompaction` (default in `AgentLoop`)
+
+`StructuredSummaryCompaction` defaults to:
+
+- count `system_prompt`, `tools`, and messages when deciding whether to compact
+- preserve protected head messages and a token-aware recent tail
+- actively prune oversized old `tool_result` blocks in the middle partition before summarization
+- record `compacted_message_ids`, `pruned_tool_results`, `fallback_used`, and a manifest on `CompactionResult`
+- keep `tools` definitions separate from `tool_result` message blocks, so pruning old tool outputs does not mutate the stable `system + tools` cache prefix
+
+For `tada-agent` integration, use `ConversationMessage.id` to preserve host message IDs. Map `CompactionResult.summary` to ReMe `_compressed_summary`, `compacted_message_ids` to `COMPRESSED` marks, and `CompactionEvent` fields to Langfuse span metadata.
+
+## What tada-core Does Not Own
+
+- Multi-provider routing, fallback, and billing: use `token-router`.
+- Product channel protocols: FastAPI, WebSocket, Feishu, DingTalk, Telegram, etc.
+- Business session storage and authentication.
+- Long-term memory or user profile retrieval.
+- Tool middleware, file upload/download, and channel-specific rendering.
+- tada-agent adapter wiring and rollout flags.
+
+## Verification
+
+```bash
+uv run pytest tests/
+uv run ruff check tada_core tests
+uv run python scripts/smoke.py
+tada-core-smoke --text "hello"
+```
+
+`scripts/smoke.py` can call echo, Anthropic-compatible, or OpenAI-compatible endpoints depending on `API_KEY`, `BASE_URL`, `MODEL_ID`, and `PROTOCOL`.

tada_core-0.2.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to `tada-core` will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses semantic versioning during public releases.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-25
+
+### Added
+
+- Public SDK surface for `AgentLoop`, `AnthropicModelClient`, events, session state, compaction strategies, and message schema models.
+- Anthropic Messages API `cache_control` support with short/long retention handling.
+- Multimodal `ContentBlock` support for image and file blocks.
+- SDK install documentation for local editable, Git URL, and future PyPI consumption.
+- `tada-core-smoke` echo-only CLI harness for manual event-stream checks.
+- Fresh-venv SDK contract verification script.
+- `ToolResultPruningConfig` plus active old `tool_result` pruning with audit manifest metadata.
+- Stable `ConversationMessage.id` propagation through `CompactionResult.compacted_message_ids`.
+
+### Changed
+
+- Clarified that provider routing belongs to `token-router`; `tada-core` owns the client-side Anthropic wire format.
+- Upgraded `StructuredSummaryCompaction` to count system/tools in thresholds, preserve token-budget tails, align tool-use boundaries, and expose richer `CompactionEvent` metadata.
+
+## [0.1.0] - 2026-05-21
+
+### Added
+
+- Initial public SDK baseline.

tada_core-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.