agentbyte 0.4.2__tar.gz → 0.4.3__tar.gz

{agentbyte-0.4.2 → agentbyte-0.4.3}/.github/skills/agentbyte-llm-client/SKILL.md

@@ -106,22 +106,41 @@ provider, embedding_client = build_embedding_client()
 ### 4. Embedding result usage (current API)
 
 ```python
-result = await embedding_client.create_batch(["alpha", "beta"])
+single = await embedding_client.create("alpha")
+vector = single.embedding
+all_vectors = single.embeddings
+tokens = single.usage.tokens_input
+cost = single.usage.cost_estimate
+```
+
+For batch input, use `embeddings`:
+
+```python
+batch = await embedding_client.create_batch(["alpha", "beta"])
 
-vectors = result.embeddings
-tokens = result.usage.tokens_input
-cost = result.usage.cost_estimate
+first_vector = batch.embedding
+vectors = batch.embeddings
+tokens = batch.usage.tokens_input
+cost = batch.usage.cost_estimate
 ```
 
 `create(...)` and `create_batch(...)` return `EmbeddingResult`.
 
+`EmbeddingResult` has this invariant:
+
+- `result.embedding == result.embeddings[0]`
+- `create(...)` returns one vector in `result.embeddings`, and the same vector is also exposed as `result.embedding`
+- `create_batch(...)` returns all vectors in `result.embeddings`, and `result.embedding` is just the first vector for convenience
+
 ## Guardrails
 
 - **Environment Loading:** Always use `load_dotenv(find_dotenv(), override=True)` before initializing clients in scripts or notebooks.
 - **Client Reuse:** Prefer creating one client instance and reusing it instead of re-initializing for each call.
 - **Factory vs. Constructor:** Use factory methods (`from_api_key`, `from_certificate`) for standard auth. Use constructor injection only for custom-configured SDK instances.
 - **Single-provider init for embeddings:** In notebooks/demos, initialize OpenAI **or** Azure (not both) to avoid missing-env failures.
-- **Embedding API shape:** Do not expect raw `list[float]` from `create(...)`; read vectors from `EmbeddingResult.embeddings`.
+- **Embedding API shape:** Do not expect raw `list[float]` from `create(...)`; read vectors from `EmbeddingResult`.
+- **Preferred field choice:** Use `result.embedding` when you expect exactly one vector. Use `result.embeddings` when you need batch-shaped output or want code that treats single and batch calls uniformly.
+- **Do not assume `embedding` is batch output:** `result.embedding` is only the first vector, even for `create_batch(...)`.
 - **Cost precision:** `usage.cost_estimate` is rounded to 15 decimals; tiny single-call embedding costs can still be very small.
 
-````
+````

agentbyte-0.4.3/.github/skills/agentbyte-plan-based-orchestration/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: agentbyte-plan-based-orchestration
+description: Guide for creating Plan-Based multi-agent orchestration in Agentbyte (Chapter 7.5). Use this when a task should be decomposed into explicit steps, assigned to specialist agents, and retried based on structured evaluation.
+license: MIT
+---
+
+Use this skill when implementing multi-agent collaboration with an explicit plan up front, step-by-step execution, evaluator-driven retries, and focused context per step.
+
+## Pattern: Basic Plan-Based Orchestration
+
+```python
+import asyncio
+from agentbyte import Agent, PlanBasedOrchestrator, UserMessage
+from agentbyte.llm import OpenAIChatCompletionClient
+from agentbyte.termination import MaxMessageTermination
+
+
+async def main():
+    # 1. Create one chat model client for planning, evaluation, and agents
+    client = OpenAIChatCompletionClient.from_api_key(
+        model="gpt-4.1-mini",
+        config={"temperature": 0.2, "max_tokens": 600},
+    )
+
+    # 2. Create specialists with clear descriptions
+    researcher = Agent(
+        name="researcher",
+        description="Research specialist for concise factual context",
+        instructions=(
+            "Gather only the facts needed for the current step and keep them concise."
+        ),
+        model_client=client,
+    )
+
+    writer = Agent(
+        name="writer",
+        description="Writing specialist for polished user-facing prose",
+        instructions=(
+            "Turn available material into concise, clear writing for the user."
+        ),
+        model_client=client,
+    )
+
+    reviewer = Agent(
+        name="reviewer",
+        description="Quality reviewer for clarity, completeness, and accuracy",
+        instructions=(
+            "Check whether the current draft satisfies the step goal and suggest "
+            "precise improvements when needed."
+        ),
+        model_client=client,
+    )
+
+    # 3. Initialize the plan-based orchestrator
+    orchestrator = PlanBasedOrchestrator(
+        agents=[researcher, writer, reviewer],
+        termination=MaxMessageTermination(12),
+        model_client=client,     # Required: used for planning and evaluation
+        max_iterations=10,       # Safety limit for total agent turns
+        max_step_retries=2,      # Retry failed steps with evaluator feedback
+        recent_messages_limit=5, # Focus context on the latest shared history
+    )
+
+    # 4. Run the task
+    task = UserMessage(
+        content="Create a short user note explaining why solar energy is beneficial.",
+        source="user",
+    )
+    result = await orchestrator.run(task)
+
+    print(f"Stop reason: {result.stop_message.content}")
+    print(f"Steps completed: {result.pattern_metadata.get('steps_completed')}")
+    print(f"Steps failed: {result.pattern_metadata.get('steps_failed')}")
+    print(f"Total retries: {result.pattern_metadata.get('total_retries')}")
+    print(f"Plan: {result.pattern_metadata.get('execution_plan')}")
+    print(f"Total tokens: {result.usage.total_tokens}")
+
+
+asyncio.run(main())
+```
+
+## Pattern: Streaming Plan-Based 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"[MSG][{item.source}] {item.content}")
+    elif isinstance(item, OrchestrationEvent):
+        print(f"[EVENT][{item.__class__.__name__}] {item}")
+    elif isinstance(item, OrchestrationResponse):
+        print(f"Complete: {item.stop_message.content}")
+        print(f"Steps completed: {item.pattern_metadata.get('steps_completed')}")
+```
+
+## How Plan-Based Orchestration Works
+
+1. The orchestrator creates a structured `ExecutionPlan`.
+2. Each `PlanStep` assigns one step to one named agent.
+3. The assigned agent receives focused context plus the current step instruction.
+4. The orchestrator evaluates the step with structured `StepProgressEvaluation`.
+5. If the step fails and retries remain, the orchestrator injects targeted retry instructions.
+6. When all steps are exhausted or completed, the orchestration stops cleanly.
+
+## Structured Models
+
+Plan-based orchestration relies on these public models:
+
+```python
+from agentbyte.orchestration.plan import (
+    ExecutionPlan,
+    PlanStep,
+    StepProgressEvaluation,
+)
+```
+
+```python
+class PlanStep(BaseModel):
+    task: str
+    agent_name: str
+    reasoning: str
+
+
+class ExecutionPlan(BaseModel):
+    steps: list[PlanStep]
+
+
+class StepProgressEvaluation(BaseModel):
+    step_completed: bool
+    failure_reason: str
+    confidence_score: float
+    suggested_improvements: list[str]
+```
+
+## Configuration Options
+
+```python
+orchestrator = PlanBasedOrchestrator(
+    agents=[agent1, agent2, agent3],  # Required: specialist agents
+    termination=termination_condition, # Required: stop condition
+    model_client=planner_client,       # Required: plan + evaluation model client
+    max_iterations=50,                 # Optional: total agent-turn safety limit
+    max_step_retries=3,                # Optional: retries per failed step
+    recent_messages_limit=5,           # Optional: focused context window
+)
+```
+
+## Pattern Metadata
+
+After completion, `result.pattern_metadata` contains plan-aware state such as:
+
+- `execution_plan`: Serialized plan steps and assignments
+- `steps_completed`: Number of successful steps
+- `steps_failed`: Number of steps exhausted after retries
+- `total_retries`: Total retry attempts across all steps
+- `current_step_index`: Final step index reached
+- `current_step_retry_count`: Retry count for the active step
+- `planner_model`: Model name used for plan/evaluation calls
+- `planner_calls`: Number of planning calls made
+- `evaluation_calls`: Number of step evaluations made
+
+## Usage Tracking
+
+Final `result.usage` includes:
+
+- all agent execution usage
+- the planning model call
+- step evaluation model calls
+
+This makes plan-based orchestration more expensive than simpler patterns, but much easier to inspect and control.
+
+## When to Use Plan-Based vs Other Patterns
+
+| Use Plan-Based When | Use AI-Driven When | Use Round-Robin When |
+|---------------------|--------------------|----------------------|
+| Work has clear phases | Routing should adapt turn by turn | Agents should alternate in fixed order |
+| You want explicit step decomposition | You want flexible specialist selection | You want deterministic sequencing |
+| Step verification matters | Flow is exploratory | Flow is simple and cyclical |
+| Retry feedback should be structured | Agent order is not known up front | Every agent should always get a turn |
+
+## Guardrails
+
+- **Model Client Required:** `PlanBasedOrchestrator` requires `model_client` for both plan generation and step evaluation.
+- **Agent Names Must Match:** `PlanStep.agent_name` must match an actual agent name. Matching is case-insensitive, but the name still has to exist.
+- **Descriptions Matter:** Agent descriptions should clearly state specialization because the planner uses them to assign steps.
+- **Termination Still Required:** Even though the pattern can stop when the plan completes, still provide a real termination condition as a safety boundary.
+- **Retries Are Bounded:** Use `max_step_retries` to keep failed steps from looping forever.
+- **Focused Context:** Plan-based orchestration intentionally sends only recent shared context plus the current step task. Do not assume every step sees the full history.
+- **Fallback Behavior Exists:** If structured planning or evaluation fails, the orchestrator falls back to safe default behavior instead of crashing.
+
+## Common Use Cases
+
+1. Research -> write -> review workflows
+2. Draft -> critique -> revise pipelines
+3. Gather evidence -> synthesize -> present answer
+4. Multi-step analyst/reporter/editor collaboration
+5. Quality-sensitive tasks where each phase should be checked before moving on
+
+## Examples
+
+- Basic: `examples/orchestration/plan_based_basic.py`
+- Streaming: `examples/orchestration/plan_based_stream.py`
+- With OTel: `examples/orchestration/plan_based_with_otel.py`

{agentbyte-0.4.2 → agentbyte-0.4.3}/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.4.3] - 2026-03-26
+
+### Added
+- Added a new Copilot skill: `agentbyte-plan-based-orchestration` for `PlanBasedOrchestrator` setup, retries, metadata, and examples.
+
+### Changed
+- Updated the `agentbyte-llm-client` skill to explain when to use `EmbeddingResult.embedding` versus `EmbeddingResult.embeddings`.
+
 ## [0.4.2] - 2026-03-25
 
 ### Added

{agentbyte-0.4.2 → agentbyte-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.4.2
+Version: 0.4.3
 Summary: A toolkit for designing multiagent systems
 Project-URL: Homepage, https://gitlab.com/pyninja/aiengineering/agentbyte
 Project-URL: Repository, https://gitlab.com/pyninja/aiengineering/agentbyte
@@ -36,17 +36,22 @@ Requires-Dist: uvicorn>=0.42.0; extra == 'webui'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.2/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.3/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
 </p>
 
 # Agentbyte
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.4.2**
+Current release: **0.4.3**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
+## What's New in 0.4.3
+
+- Added a new `agentbyte-plan-based-orchestration` Copilot skill for Chapter 7.5 plan-based orchestration.
+- Updated the `agentbyte-llm-client` skill to document `EmbeddingResult.embedding` versus `EmbeddingResult.embeddings`.
+
 ## What's New in 0.4.2
 
 - Rebased the WebUI source frontend on the picoagents frontend snapshot copied into `src/agentbyte/webui/frontend/`.

{agentbyte-0.4.2 → agentbyte-0.4.3}/README.md

@@ -1,15 +1,20 @@
 <p align="center">
-  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.2/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.3/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
 </p>
 
 # Agentbyte
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.4.2**
+Current release: **0.4.3**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
+## What's New in 0.4.3
+
+- Added a new `agentbyte-plan-based-orchestration` Copilot skill for Chapter 7.5 plan-based orchestration.
+- Updated the `agentbyte-llm-client` skill to document `EmbeddingResult.embedding` versus `EmbeddingResult.embeddings`.
+
 ## What's New in 0.4.2
 
 - Rebased the WebUI source frontend on the picoagents frontend snapshot copied into `src/agentbyte/webui/frontend/`.

{agentbyte-0.4.2 → agentbyte-0.4.3}/src/agentbyte/__about__.py

@@ -1,2 +1,2 @@
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 VERSION = __version__