agentbyte 0.4.7__tar.gz → 0.5.0__tar.gz

{agentbyte-0.4.7 → agentbyte-0.5.0}/.github/skills/agentbyte-ai-driven-orchestration/SKILL.md

@@ -6,13 +6,32 @@ license: MIT
 
 Use this skill when implementing multi-agent collaboration where an LLM intelligently selects which agent should respond next based on conversation context and agent capabilities.
 
+## Inputs to confirm
+- Which agents are available and how clearly their descriptions express specialization
+- What should stop the orchestration
+- Whether the selector should see a compact summary or a richer selector context
+- Whether worker agents should receive full history or a narrower execution history
+
 ## Pattern: Basic AI-Driven Orchestration
 
 ```python
 import asyncio
-from agentbyte import AIOrchestrator, Agent, UserMessage
+from agentbyte import (
+    AIOrchestrator,
+    Agent,
+    AgentHistoryPolicy,
+    HistoryContextPolicy,
+    SelectorContextPolicy,
+    UserMessage,
+)
 from agentbyte.llm import OpenAIChatCompletionClient
-from agentbyte.termination import MaxMessageTermination, TextMentionTermination
+from agentbyte.termination import (
+    ConsecutiveAgentTermination,
+    MaxMessageTermination,
+    PredicateTermination,
+    SourceTermination,
+    TextMentionTermination,
+)
 
 async def main():
     # 1. Create model client
@@ -40,14 +59,28 @@ async def main():
     )
 
     # 3. Define termination conditions
-    termination = MaxMessageTermination(8) | TextMentionTermination("TERMINATE")
+    # ConsecutiveAgentTermination guards against the selector routing to the same
+    # agent repeatedly — the most common failure mode in AI-driven orchestration
+    termination = (
+        ConsecutiveAgentTermination(max_consecutive=3)
+        | TextMentionTermination("TERMINATE")
+        | MaxMessageTermination(8)
+    )
 
     # 4. Initialize AI orchestrator (requires model_client for selection)
     orchestrator = AIOrchestrator(
         agents=[researcher, writer],
         termination=termination,
         model_client=client,  # Required: LLM for agent selection
-        max_iterations=6
+        max_iterations=6,
+        history_policy=HistoryContextPolicy(
+            default=AgentHistoryPolicy(window="full", format="text")
+        ),
+        selector_policy=SelectorContextPolicy(
+            window="recent",
+            message_limit=12,
+            format="summary",
+        ),
     )
 
     # 5. Run the collaboration
@@ -87,25 +120,47 @@ async for item in orchestrator.run_stream(task, verbose=True):
 3. **Reasoning Included:** Selection events include the LLM's reasoning for why it chose that agent
 4. **Fallback Safety:** If LLM selection fails or returns invalid agent name, falls back to round-robin
 
-## Configuration Options
+## Policy Surface
 
 ```python
 orchestrator = AIOrchestrator(
-    agents=[agent1, agent2, agent3],     # Required: List of agents
-    termination=termination_condition,    # Required: When to stop
-    model_client=selection_model_client,  # Required: LLM for agent selection
-    max_iterations=10,                    # Optional: Safety limit (default: 10)
-    verbose=False                         # Optional: Enable event logging
+    agents=[agent1, agent2, agent3],
+    termination=termination_condition,
+    model_client=selection_model_client,
+    max_iterations=10,
+    history_policy=HistoryContextPolicy(
+        default=AgentHistoryPolicy(window="full", format="text")
+    ),
+    selector_policy=SelectorContextPolicy(
+        window="recent",
+        message_limit=12,
+        format="summary",
+    ),
 )
 ```
 
+Use the two policies for different jobs:
+- `HistoryContextPolicy`: contains a default `AgentHistoryPolicy` plus optional per-agent `AgentHistoryPolicy` overrides for worker execution
+- `SelectorContextPolicy`: controls what the selector model sees when deciding which agent should go next
+
+`AgentHistoryPolicy` is the per-agent rule that actually defines:
+- `window`
+- `message_limit`
+- `format`
+- `include_turn_prompt`
+
+Selector formatting affects routing quality:
+- `summary` is compact and best for many coordination tasks
+- `markdown` can help readability on long transcripts
+- `json` can help when explicit role/source/content structure matters
+
 ## Pattern Metadata
 
 After completion, `result.pattern_metadata` contains:
 - `iterations_completed`: Total agent executions
 - `selector_calls`: Number of LLM selection calls made
-- `fallback_count`: How many times round-robin fallback was used
-- `final_reason`: Why orchestration stopped
+- `selector_model`: Model used for routing
+- `selector_policy`: Serialized selector-context configuration
 
 ## Usage Tracking
 
@@ -132,12 +187,56 @@ description="A helpful agent"  # Too vague
 description="Agent 1"  # No capability info
 ```
 
+## Termination Conditions
+
+| Termination Type | Purpose | AI-Driven relevance |
+|-----------------|---------|---------------------|
+| `ConsecutiveAgentTermination(n)` | Stop when same agent selected n times in a row | **Primary loop guard** — always include |
+| `MaxMessageTermination(n)` | Stop after n messages | Hard safety cap |
+| `TextMentionTermination("X")` | Stop when any agent says X | Semantic completion signal |
+| `SourceTermination("name")` | Stop when a specific agent speaks | Phase-transition stop (e.g. reviewer responded) |
+| `PredicateTermination(fn)` | Stop on any custom callable condition | Custom quality or content checks |
+| `TimeoutTermination(sec)` | Stop after elapsed time | Latency-sensitive systems |
+| `TokenUsageTermination(n)` | Stop after n tokens | Cost control |
+
+### Recommended baseline for AI-driven orchestration
+
+```python
+termination = (
+    ConsecutiveAgentTermination(max_consecutive=3)  # loop guard
+    | TextMentionTermination("TERMINATE")            # semantic stop
+    | MaxMessageTermination(12)                      # hard cap
+)
+```
+
+### When the workflow ends when a specific agent has responded
+
+```python
+# Stop as soon as the reviewer speaks
+termination = SourceTermination("reviewer") | MaxMessageTermination(10)
+
+# Stop only when the reviewer approves in the same message
+termination = (
+    PredicateTermination(
+        lambda msgs: any(
+            getattr(m, "source", None) == "reviewer"
+            and "APPROVED" in str(getattr(m, "content", ""))
+            for m in msgs
+        ),
+        reason="Reviewer approved",
+    )
+    | ConsecutiveAgentTermination(max_consecutive=3)
+    | MaxMessageTermination(12)
+)
+```
+
 ## Guardrails
 
 - **Model Client Required:** `AIOrchestrator` needs a `model_client` parameter for agent selection (unlike `RoundRobinOrchestrator`).
 - **Clear Descriptions:** Write specific agent descriptions—the LLM uses these to decide who should respond.
-- **Termination Required:** Always provide termination conditions to prevent infinite loops.
-- **Safety Fallback:** If LLM selection fails, orchestrator falls back to round-robin (check `fallback_count` in metadata).
+- **Two Context Surfaces:** Do not confuse `history_policy` with `selector_policy`; one shapes execution, the other shapes routing.
+- **Termination Required:** Always provide termination conditions to prevent infinite loops. Include `ConsecutiveAgentTermination` — repeated same-agent selection is the most common AI-driven failure mode.
+- **Safety Fallback:** If LLM selection fails, the orchestrator falls back to round-robin selection to preserve forward progress.
 - **Usage Accounting:** Final usage includes both agent tokens AND selector tokens.
 - **Case Insensitive:** Agent name matching is case-insensitive for robustness.
 - **Event Observability:** Use `verbose=True` with `run_stream()` to see AI selection reasoning.
@@ -160,12 +259,6 @@ description="Agent 1"  # No capability info
 4. **Dynamic Collaboration:** Agents with overlapping capabilities—LLM picks best fit
 5. **Question Routing:** Route user questions to the most appropriate agent based on content
 
-## Examples
-
-- Basic: `examples/orchestration/ai_driven_basic.py`
-- Streaming: `examples/orchestration/ai_driven_stream.py`
-- With OTel: `examples/orchestration/ai_driven_with_otel.py`
-
 ## OpenTelemetry Integration
 
 For observability with Jaeger:

{agentbyte-0.4.7 → agentbyte-0.5.0}/.github/skills/agentbyte-dataset/SKILL.md

@@ -6,13 +6,16 @@ description: Guide for creating and using Agentbyte datasets with SQLite or JSON
 Use this skill when you need to:
 - **Load** an existing dataset using `load_dataset()`
 - **Create** a new dataset with config.json, schema.json, and data.json
+- **Load** the same dataset structure from local disk or S3
 - **Query** SQLite datasets with SQL or iterate JSON datasets
 - **Display** dataset schemas in pretty or raw format
 - **Work with** multiple data engines (SQLite for structured, JSON for semi-structured)
 
 ## Dataset Architecture
 
-Agentbyte datasets are file-based and engine-agnostic. Each dataset lives in `data/samples/{category}/{name}/` with three files:
+Agentbyte datasets are file-based and engine-agnostic. The dataset contract stays the same whether the files live on local disk or in S3.
+
+Local layout:
 
 ### File Structure
 ```
@@ -22,6 +25,14 @@ data/samples/{category}/{name}/
 └── data.json        # Records only ({"records": [...]})
 ```
 
+Equivalent S3 layout:
+```
+s3://<bucket>/<optional-prefix>/{category}/{name}/
+├── config.json
+├── schema.json
+└── data.json
+```
+
 ### Supported Engines
 - **sqlite** (default): Structured data with SQL queries, strict schema, constraints
 - **json**: Semi-structured data, flexible JSON format, inferred schema
@@ -92,11 +103,23 @@ with open(dataset_dir / "data.json", "w") as f:
 
 ### Load a Dataset
 ```python
-from agentbyte.dataset import load_dataset
+from pathlib import Path
 
-ds = load_dataset("category/name")  # Returns SQLiteDataset or JSONDataset
+from agentbyte.dataset import LocalDatasetConfig, S3DatasetConfig, load_dataset
+
+# Local source
+local_config = LocalDatasetConfig(local_root=Path("data/samples"))
+ds = load_dataset("category/name", local_config)  # Returns SQLiteDataset or JSONDataset
 print(ds.engine)        # "sqlite" or "json"
 print(ds.table_name)    # Table/collection name
+
+# S3 source
+s3_config = S3DatasetConfig(
+    s3_bucket="datapsycho-datasets",
+    s3_region="eu-west-1",
+    s3_prefix="datasets",
+)
+ds_s3 = load_dataset("category/name", s3_config)
 ```
 
 ### Connect & Get Data
@@ -134,9 +157,11 @@ ds.schema.show(format=SchemaFormat.RAW)
 
 ### Example 1: Load & Query Existing SQLite Dataset
 ```python
-from agentbyte.dataset import load_dataset
+from pathlib import Path
 
-ds = load_dataset("contracts/asmd")
+from agentbyte.dataset import LocalDatasetConfig, load_dataset
+
+ds = load_dataset("contracts/asmd", LocalDatasetConfig(local_root=Path("data/samples")))
 conn = ds.connect()
 
 # Display schema
@@ -153,7 +178,11 @@ for row in active:
 
 ### Example 2: Load & Iterate JSON Dataset
 ```python
-ds = load_dataset("documents/wiki")  # engine="json" in config
+from pathlib import Path
+
+from agentbyte.dataset import LocalDatasetConfig, load_dataset
+
+ds = load_dataset("documents/wiki", LocalDatasetConfig(local_root=Path("data/samples")))
 data = ds.connect()  # dict with {"records": [...]}
 
 for i, record in enumerate(data["records"], 1):
@@ -163,13 +192,31 @@ for i, record in enumerate(data["records"], 1):
 ### Example 3: Create Dataset Programmatically
 See "Creating a Dataset" section above for step-by-step code.
 
+### Example 4: Load From S3
+```python
+from agentbyte.dataset import S3DatasetConfig, load_dataset
+
+s3_config = S3DatasetConfig(
+    s3_bucket="datapsycho-datasets",
+    s3_region="eu-west-1",
+    s3_prefix="datasets",
+)
+
+ds = load_dataset("contracts10/asmd", s3_config)
+conn = ds.connect()
+rows = conn.execute("SELECT * FROM contracts_asmd").fetchall()
+```
+
 ## Guardrails
 
-- **Do** use relative paths from project root in `load_dataset()` (e.g., `"contracts/asmd"`, not full file paths).
+- **Do** use canonical dataset IDs in `load_dataset()` (e.g., `"contracts/asmd"`, not full file paths).
+- **Do** pass a source config object to `load_dataset()` (`LocalDatasetConfig` or `S3DatasetConfig`).
+- **Do** keep `dataset_id` logical (`"category/name"`) and configure S3 location through `S3DatasetConfig`.
 - **Do** keep schema.json separate from data.json for clarity and reusability.
 - **Do** use `dict(row)` to convert sqlite3.Row objects to dicts for JSON serialization.
 - **Do** call `ds.connect()` only once; it caches the connection and schema on first call.
 - **Don't** hard-code values in datasets (use config.json for metadata).
+- **Don't** store bucket names or S3 prefixes inside `config.json`.
 - **Don't** forget `.json` extensions for all three files.
 - **Don't** put schema definitions inside data.json (separate files for clarity).
 - **Don't** assume JSON datasets support SQL—use dict iteration instead.
@@ -178,9 +225,19 @@ See "Creating a Dataset" section above for step-by-step code.
 
 ### Factory Function
 ```python
-load_dataset(dataset_id: str) -> BaseDataset
+load_dataset(
+    dataset_id: str,
+    config: DatasetSourceConfig,
+) -> BaseDataset
 ```
-Loads dataset from `data/samples/{category}/{name}/`. Returns `SQLiteDataset` or `JSONDataset` based on config.engine.
+Loads dataset using the provided source config (`LocalDatasetConfig` or
+`S3DatasetConfig`). Returns `SQLiteDataset` or `JSONDataset` based on
+`config.engine`.
+
+### Source Config Types
+- **DatasetSourceConfig**: Abstract config contract
+- **LocalDatasetConfig**: Local source config with `local_root`
+- **S3DatasetConfig**: S3 source config with `s3_bucket`, `s3_region`, `s3_prefix`
 
 ### Classes (Generic)
 - **Column**: name (str), type (str)
@@ -203,6 +260,8 @@ Loads dataset from `data/samples/{category}/{name}/`. Returns `SQLiteDataset` or
 |-------|-----|
 | `FileNotFoundError: Schema file not found` | Ensure `schema.json` exists in dataset directory |
 | `FileNotFoundError: Data file not found` | Ensure `data.json` exists in dataset directory |
+| `FileNotFoundError: Dataset object not found: s3://...` | Ensure the bucket, prefix, dataset_id, and object names are correct |
+| `ValidationError: s3_bucket field required` | Set `AGENTBYTE_DATASET_S3_BUCKET` or pass `S3DatasetConfig(s3_bucket=...)` |
 | `KeyError: 'records'` | data.json must have `{"records": [...]}` structure |
 | `sqlite3.Row has no .dict() method` | Use `dict(row)` instead of `row.dict()` |
-| Notebook paths fail in `load_dataset()` | Use relative paths from project root; notebook working directory is handled by loader |
+| Notebook paths fail in `load_dataset()` | Pass an explicit `LocalDatasetConfig(local_root=Path("data/samples"))` |

agentbyte-0.5.0/.github/skills/agentbyte-handoff-orchestration/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: agentbyte-handoff-orchestration
+description: Guide for creating Handoff multi-agent orchestration in Agentbyte (Chapter 7.6). Use this when agents should explicitly transfer control to named colleagues with `HANDOFF: <agent_name>` instead of the orchestrator centrally selecting every next turn.
+license: MIT
+---
+
+Use this skill when implementing multi-agent collaboration where the currently speaking agent should decide which specialist goes next.
+
+## Inputs to confirm
+- Which agent should start first
+- What exact handoff signal agents should emit
+- What should happen when no valid handoff signal is present
+- What termination condition should actually stop the run
+- Whether colleagues should be injected into agent context automatically
+
+## Pattern: Basic Handoff Orchestration
+
+```python
+import asyncio
+
+from agentbyte import Agent, HandoffOrchestrator, UserMessage
+from agentbyte.llm import OpenAIChatCompletionClient
+from agentbyte.termination import MaxMessageTermination, TextMentionTermination
+
+
+async def main() -> None:
+    client = OpenAIChatCompletionClient.from_api_key(model="gpt-4o-mini")
+
+    researcher = Agent(
+        name="researcher",
+        description="Research specialist for concise factual context",
+        instructions=(
+            "Research the topic and gather the key facts. "
+            "When the writer should continue, write exactly: HANDOFF: writer"
+        ),
+        model_client=client,
+    )
+
+    writer = Agent(
+        name="writer",
+        description="Writing specialist for clear user-facing drafts",
+        instructions=(
+            "Write a concise draft using the available context. "
+            "When the reviewer should inspect it, write exactly: HANDOFF: reviewer"
+        ),
+        model_client=client,
+    )
+
+    reviewer = Agent(
+        name="reviewer",
+        description="Review specialist for clarity and correctness",
+        instructions=(
+            "Review the draft. If it is ready, say APPROVED. "
+            "If it needs revision, give concise feedback and write exactly: HANDOFF: writer"
+        ),
+        model_client=client,
+    )
+
+    termination = TextMentionTermination("APPROVED") | MaxMessageTermination(12)
+
+    orchestrator = HandoffOrchestrator(
+        agents=[researcher, writer, reviewer],
+        termination=termination,
+        entry_agent_name="researcher",
+        fallback_strategy="round_robin",
+        handoff_signal_prefix="HANDOFF:",
+        inject_colleagues_context=True,
+        max_iterations=10,
+    )
+
+    task = UserMessage(
+        content="Write a short note about solar energy benefits.",
+        source="user",
+    )
+    result = await orchestrator.run(task)
+
+    print(f"Stop reason: {result.stop_message.content}")
+    print(f"Handoffs: {result.pattern_metadata['handoff_counts']}")
+    print(f"Last target: {result.pattern_metadata['last_handoff_target']}")
+
+
+asyncio.run(main())
+```
+
+## Pattern: Streaming Handoff Orchestration
+
+```python
+from agentbyte.messages import Message
+from agentbyte.types import OrchestrationEvent, OrchestrationResponse
+
+async for item in orchestrator.run_stream(task, verbose=True):
+    if isinstance(item, Message):
+        print(f"[{item.source}] {item.content}")
+    elif isinstance(item, OrchestrationEvent):
+        print(f"[EVENT] {item}")
+    elif isinstance(item, OrchestrationResponse):
+        print(f"Complete: {item.stop_message.content}")
+```
+
+## How Handoff Routing Works
+
+1. The first turn goes to the entry agent.
+2. The current agent may emit `HANDOFF: <agent_name>` in its response.
+3. The orchestrator parses the latest assistant response for that signal.
+4. If the target agent exists, control transfers there.
+5. If no valid signal is present, the configured fallback strategy is used.
+
+This means:
+- agents own the routing intent
+- the orchestrator still owns validation, execution safety, and shared state
+
+## Constructor Surface
+
+```python
+orchestrator = HandoffOrchestrator(
+    agents=[agent1, agent2, agent3],
+    termination=termination_condition,
+    entry_agent_name="agent1",
+    fallback_strategy="round_robin",   # or "entry"
+    handoff_signal_prefix="HANDOFF:",
+    inject_colleagues_context=True,
+    max_iterations=50,
+    history_policy=...,
+)
+```
+
+## Fallback Strategies
+
+Use `fallback_strategy="round_robin"` when:
+- you want forward progress even if an agent forgets to hand off
+- multiple specialists can still contribute usefully
+
+Use `fallback_strategy="entry"` when:
+- one lead agent should always re-triage the task
+- the entry agent acts like a hub/router
+
+## Colleagues Context Injection
+
+When `inject_colleagues_context=True`, each agent receives a short block listing:
+- the other agents it can hand off to
+- their descriptions
+- the reminder to use `HANDOFF: <name>`
+
+Keep this enabled unless you already embed the routing protocol clearly in agent instructions and need tighter context control.
+
+## History Policy
+
+`HandoffOrchestrator` still uses `HistoryContextPolicy` for execution context:
+
+```python
+from agentbyte import AgentHistoryPolicy, HistoryContextPolicy
+
+history_policy = HistoryContextPolicy(
+    default=AgentHistoryPolicy(window="full", format="text"),
+    per_agent={
+        "reviewer": AgentHistoryPolicy(
+            window="recent",
+            message_limit=4,
+            format="markdown",
+        )
+    },
+)
+```
+
+Important mental model:
+- handoff chooses who acts next
+- history policy chooses what that agent sees
+
+## Recommended Termination Patterns
+
+### Basic reviewer approval flow
+
+```python
+termination = TextMentionTermination("APPROVED") | MaxMessageTermination(12)
+```
+
+### Reviewer-specific approval in the same message
+
+```python
+from agentbyte.termination import MaxMessageTermination, PredicateTermination
+
+termination = (
+    PredicateTermination(
+        lambda msgs: any(
+            getattr(m, "source", None) == "reviewer"
+            and "APPROVED" in str(getattr(m, "content", ""))
+            for m in msgs
+        ),
+        reason="Reviewer approved",
+    )
+    | MaxMessageTermination(12)
+)
+```
+
+### Production-oriented safety bundle
+
+```python
+from agentbyte.termination import (
+    MaxMessageTermination,
+    PredicateTermination,
+    TimeoutTermination,
+    TokenUsageTermination,
+)
+
+termination = (
+    PredicateTermination(...)
+    | TimeoutTermination(120)
+    | TokenUsageTermination(8_000)
+    | MaxMessageTermination(12)
+)
+```
+
+## Pattern Metadata
+
+After completion, `result.pattern_metadata` includes:
+- `entry_agent`
+- `fallback_strategy`
+- `handoff_signal_prefix`
+- `handoff_counts`
+- `last_handoff_target`
+- inherited base metrics like `iterations_completed` and `message_count`
+
+## Guardrails
+
+- **Termination Still Required:** Handoff decides who goes next, not when to stop.
+- **Stable Agent Names:** Keep agent names short and unambiguous because routing depends on matching text.
+- **Explicit Protocol:** Tell agents to emit the exact signal, e.g. `HANDOFF: reviewer`.
+- **Fallback Is Important:** Missing or malformed handoff text should not end the run or crash the orchestrator.
+- **Colleague Descriptions Matter:** The injected colleagues block is more useful when agent descriptions clearly explain specialization.
+- **Text-Based Routing:** This pattern is lighter than AI-driven selection, but also less strict than structured-output routing.
+
+## When to Use Handoff vs Other Patterns
+
+| Use Handoff When | Use AI-Driven When | Use Round-Robin When | Use Plan-Based When |
+|------------------|--------------------|----------------------|---------------------|
+| The current agent usually knows the best next specialist | A central selector model should reason over the whole state | All agents should contribute in fixed order | The task has explicit sequential phases |
+| You want decentralized routing | You want selector reasoning as a separate coordination call | Deterministic sequencing matters most | You need evaluator-driven retries and explicit step structure |
+| You want specialist chaining like research -> write -> review -> revise | You want more robust routing than a text signal | You want the simplest possible coordination | You want decomposition before execution |
+
+## Common Use Cases
+
+1. Research -> write -> review workflows
+2. Reviewer -> writer revision loops
+3. Support triage -> billing specialist -> support resolution flows
+4. Specialist chains where the current agent can naturally identify the next specialist
+5. Lower-cost adaptive routing without a separate selector model