agentbyte 0.3.6__tar.gz → 0.4.2__tar.gz

agentbyte-0.4.2/.github/skills/agentbyte-ai-driven-orchestration/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: agentbyte-ai-driven-orchestration
+description: Guide for creating AI-Driven multi-agent orchestration in Agentbyte (Chapter 7.4). Use this when you need LLM-based adaptive agent selection instead of fixed turn sequences.
+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.
+
+## Pattern: Basic AI-Driven Orchestration
+
+```python
+import asyncio
+from agentbyte import AIOrchestrator, Agent, UserMessage
+from agentbyte.llm import OpenAIChatCompletionClient
+from agentbyte.termination import MaxMessageTermination, TextMentionTermination
+
+async def main():
+    # 1. Create model client
+    client = OpenAIChatCompletionClient.from_api_key(model="gpt-4o-mini")
+
+    # 2. Create agents with clear descriptions (LLM uses these for selection)
+    researcher = Agent(
+        name="researcher",
+        description="Research specialist for factual and contextual information",
+        instructions=(
+            "You are a research specialist. Provide concise factual insights "
+            "and clarify missing context when needed."
+        ),
+        model_client=client
+    )
+
+    writer = Agent(
+        name="writer",
+        description="Content specialist for polished user-facing writing",
+        instructions=(
+            "You are a writer. Synthesize available information into concise, "
+            "high-quality prose. End with TERMINATE when complete."
+        ),
+        model_client=client
+    )
+
+    # 3. Define termination conditions
+    termination = MaxMessageTermination(8) | TextMentionTermination("TERMINATE")
+
+    # 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
+    )
+
+    # 5. Run the collaboration
+    task = UserMessage(
+        content="Write a short note about the benefits of solar energy",
+        source="user"
+    )
+    
+    result = await orchestrator.run(task)
+
+    print(f"Stop reason: {result.stop_message.content}")
+    print(f"Iterations: {result.pattern_metadata.get('iterations_completed')}")
+    print(f"Selector calls: {result.pattern_metadata.get('selector_calls')}")
+    print(f"Total tokens: {result.usage.total_tokens}")
+
+asyncio.run(main())
+```
+
+## Pattern: Streaming AI-Driven Orchestration
+
+```python
+async for item in orchestrator.run_stream(task, verbose=True):
+    if isinstance(item, Message):
+        print(f"[{item.source}] {item.content}")
+    elif isinstance(item, OrchestrationEvent):
+        # AgentSelectionEvent includes AI reasoning
+        if hasattr(item, 'reason'):
+            print(f"Selection reason: {item.reason}")
+    elif isinstance(item, OrchestrationResponse):
+        print(f"Complete: {item.stop_message.content}")
+```
+
+## How AI Selection Works
+
+1. **Structured Output:** The orchestrator uses LLM with structured output (`AgentSelection` schema) to select the next agent
+2. **Context Awareness:** The LLM sees conversation history and all agent descriptions
+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
+
+```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
+)
+```
+
+## 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
+
+## Usage Tracking
+
+The orchestrator tracks token usage from:
+- All agent executions
+- All selector LLM calls (agent selection)
+
+Final `result.usage` includes comprehensive totals across all LLM interactions.
+
+## Agent Description Best Practices
+
+The LLM uses agent descriptions to make selection decisions. Write clear, specific descriptions:
+
+✅ **Good:**
+```python
+description="Research specialist for factual and contextual information"
+description="Content specialist for polished user-facing writing"
+description="Code reviewer that checks for bugs and style issues"
+```
+
+❌ **Avoid:**
+```python
+description="A helpful agent"  # Too vague
+description="Agent 1"  # No capability info
+```
+
+## 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).
+- **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.
+
+## When to Use AI-Driven vs Round-Robin
+
+| Use AI-Driven When | Use Round-Robin When |
+|--------------------|----------------------|
+| Agent roles are specialized | Agents always alternate (poet/critic) |
+| Order should adapt to context | Fixed workflow is desired |
+| You have 3+ agents | You have exactly 2 agents |
+| Complexity requires smart routing | Simple back-and-forth suffices |
+| You want LLM to decide flow | You want deterministic order |
+
+## Common Use Cases
+
+1. **Research → Write → Review:** LLM decides when research is sufficient, when to write, when to review
+2. **Multi-Specialist Teams:** Route to the right expert (data analyst, writer, coder, reviewer)
+3. **Adaptive Workflows:** Let LLM determine optimal agent sequence based on task complexity
+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:
+
+```python
+import os
+# Set BEFORE importing agentbyte
+os.environ["AGENTBYTE_ENABLE_OTEL"] = "true"
+os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4318"
+os.environ["OTEL_SERVICE_NAME"] = "my-ai-orchestration"
+
+from agentbyte import AIOrchestrator
+# ... rest of code
+```
+
+Traces will show:
+- Orchestration span (parent)
+- Selector LLM calls (for agent selection)
+- Individual agent execution spans
+- Token usage aggregated at orchestration level

agentbyte-0.4.2/.github/skills/agentbyte-round-robin-orchestration/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: agentbyte-round-robin-orchestration
+description: Guide for creating Round-Robin multi-agent orchestration in Agentbyte. Use this when coordinating multiple agents in sequential turns until a termination condition is met.
+license: MIT
+---
+
+Use this skill when implementing multi-agent collaboration where agents take turns in a fixed sequence (poet/critic, research/writing, review/revise patterns).
+
+## Pattern: Basic Round-Robin Orchestration
+
+```python
+import asyncio
+from agentbyte import RoundRobinOrchestrator, Agent, UserMessage
+from agentbyte.llm import OpenAIChatCompletionClient
+from agentbyte.termination import MaxMessageTermination, TextMentionTermination
+
+async def main():
+    # 1. Create model client
+    client = OpenAIChatCompletionClient.from_api_key(model="gpt-4o-mini")
+
+    # 2. Create agents
+    poet = Agent(
+        name="poet",
+        description="A creative poet that writes and refines haikus",
+        instructions="Write a haiku. If you received feedback, refine it.",
+        model_client=client
+    )
+
+    critic = Agent(
+        name="critic",
+        description="A strict poetry critic",
+        instructions="Review the poem. If good, say APPROVED. Else provide feedback.",
+        model_client=client
+    )
+
+    # 3. Define termination conditions (composable with | and &)
+    termination = TextMentionTermination("APPROVED") | MaxMessageTermination(6)
+
+    # 4. Initialize orchestrator
+    orchestrator = RoundRobinOrchestrator(
+        agents=[poet, critic],
+        termination=termination,
+        max_iterations=10  # Safety fallback
+    )
+
+    # 5. Run the collaboration
+    task = UserMessage(content="Write a haiku about programming", source="user")
+    result = await orchestrator.run(task)
+
+    print(f"Stop reason: {result.stop_message.content}")
+    print(f"Total tokens: {result.usage.total_tokens}")
+    print(f"Cycles: {result.pattern_metadata['cycles_completed']}")
+
+asyncio.run(main())
+```
+
+## Pattern: Streaming Round-Robin
+
+```python
+async for item in orchestrator.run_stream(task, verbose=True):
+    if isinstance(item, Message):
+        print(f"[{item.source}] {item.content}")
+    elif isinstance(item, OrchestrationEvent):
+        # Track selection, execution events
+        print(f"Event: {item.__class__.__name__}")
+    elif isinstance(item, OrchestrationResponse):
+        # Final result
+        print(f"Complete: {item.stop_message.content}")
+```
+
+## Available Termination Conditions
+
+| Termination Type | Purpose | Example |
+|-----------------|---------|---------|
+| `MaxMessageTermination(n)` | Stop after n messages | `MaxMessageTermination(10)` |
+| `TextMentionTermination("X")` | Stop when text appears | `TextMentionTermination("APPROVED")` |
+| `TokenUsageTermination(n)` | Stop after n tokens | `TokenUsageTermination(5000)` |
+| `TimeoutTermination(sec)` | Stop after timeout | `TimeoutTermination(60.0)` |
+| `CancellationTermination()` | Stop when cancelled | `CancellationTermination()` |
+| Composite (OR) | Stop if any condition met | `T1 \| T2 \| T3` |
+| Composite (AND) | Stop if all conditions met | `T1 & T2 & T3` |
+
+## Configuration Options
+
+```python
+orchestrator = RoundRobinOrchestrator(
+    agents=[agent1, agent2, agent3],  # Required: List of agents
+    termination=termination_condition,  # Required: When to stop
+    max_iterations=10,                  # Optional: Safety limit (default: 10)
+    verbose=False                        # Optional: Enable event logging
+)
+```
+
+## Pattern Metadata
+
+After completion, `result.pattern_metadata` contains:
+- `cycles_completed`: Number of full round-robin cycles
+- `iterations_completed`: Total agent executions
+- `final_reason`: Why orchestration stopped
+
+## Guardrails
+
+- **Agent Order:** Agents execute in the order provided in the `agents` list.
+- **Termination Required:** Always provide at least one termination condition to prevent infinite loops.
+- **Safety Limit:** Set `max_iterations` as a failsafe even with other termination conditions.
+- **Shared Context:** All agents see the full conversation history from previous turns.
+- **Model Client:** Each agent needs its own `model_client` configured.
+- **Event Observability:** Use `verbose=True` with `run_stream()` to track selection and execution events.
+
+## Common Use Cases
+
+1. **Poet/Critic Pattern:** Writer creates, reviewer approves or requests changes
+2. **Research/Writing:** Researcher gathers facts, writer synthesizes into prose
+3. **Code/Review:** Developer writes code, reviewer provides feedback
+4. **Plan/Execute:** Planner designs approach, executor implements steps
+5. **Draft/Polish:** Rough draft agent, then polish/editing agent
+
+## Examples
+
+- Basic: `examples/orchestration/round_robin_basic.py`
+- With OTel: `examples/orchestration/orchestrator_with_otel.py`
+- Termination demo: `examples/orchestration/termination_demo.py`

{agentbyte-0.3.6 → agentbyte-0.4.2}/.gitignore

@@ -16,6 +16,8 @@ wheels/
 *.swp
 *.swo
 *~
+node_modules/
+*.tsbuildinfo
 
 # OS
 .DS_Store
@@ -37,4 +39,4 @@ htmlcov/
 
 docs/chapters/
 data/Designing-Multi-Agent-Systems.pdf
-artifacts/
+artifacts/

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

@@ -4,6 +4,56 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.4.2] - 2026-03-25
+
+### Added
+- Added the copied picoagents `agent_framework_devui` assets under `src/agentbyte/webui/` for local parity/reference work.
+- Added the upstream frontend workspace files that now live under `src/agentbyte/webui/frontend/`, including new public assets and shared UI components.
+
+### Changed
+- Replaced the previous in-repo WebUI frontend source with the picoagents frontend snapshot copied into `src/agentbyte/webui/frontend/`.
+- Removed the redundant Hatch wheel `force-include` for `src/agentbyte/webui/ui`, fixing duplicate archive entries during wheel builds.
+
+### Fixed
+- Fixed PyPI publish failures caused by duplicate `agentbyte/webui/ui/*` filenames in the generated wheel.
+
+## [0.4.1] - 2026-03-25
+
+### Added
+- Added a single-vector `embedding` field to `EmbeddingResult` while preserving the existing `embeddings`, `usage`, `model`, and `metadata` payload.
+
+### Changed
+- Updated OpenAI and Azure embedding clients so `create()` and `create_batch()` both return an `EmbeddingResult` with `embedding == embeddings[0]`.
+- Shipped the packaged Chapter 8 WebUI assets and parity updates that landed after `0.4.0`.
+
+### Testing
+- Added focused embedding assertions for the dual-field result contract across OpenAI and Azure embedding clients.
+
+## [0.4.0] - 2026-03-24
+
+### Added
+- New multi-agent orchestration module with shared `BaseOrchestrator` execution loop.
+- New orchestration patterns:
+  - `RoundRobinOrchestrator`
+  - `AIOrchestrator`
+  - `PlanBasedOrchestrator`
+- New plan-based orchestration public models:
+  - `PlanStep`
+  - `ExecutionPlan`
+  - `StepProgressEvaluation`
+- New orchestration examples for basic, streaming, and OpenTelemetry-backed execution.
+- New Chapter 7 study/tutorial docs for round-robin, AI-driven, and plan-based orchestration.
+
+### Changed
+- Extended orchestration execution to support focused message-list context payloads and pattern-level completion hooks.
+- Improved agent-as-tool streaming telemetry so tool middleware spans are preserved for delegated agent execution.
+- Added aggregate usage summaries on workflow and orchestration root spans while keeping detailed `chat ...` and `tool ...` spans at the agent/middleware layer.
+- Updated study docs to clarify the telemetry boundary across agents, workflows, and orchestrators.
+
+### Testing
+- Added dedicated tests for plan-based orchestration behavior and package-level export coverage.
+- Added telemetry regression coverage for delegated agent-as-tool execution and workflow root usage summaries.
+
 ## [0.3.6] - 2026-03-23
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.3.6
+Version: 0.4.2
 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
@@ -15,10 +15,12 @@ Requires-Dist: pydantic-settings>=2.13.0
 Requires-Dist: pydantic>=2.12.5
 Provides-Extra: all
 Requires-Dist: azure-identity>=1.25.1; extra == 'all'
+Requires-Dist: fastapi>=0.135.2; extra == 'all'
 Requires-Dist: openai>=1.107.1; extra == 'all'
 Requires-Dist: opentelemetry-api>=1.39.1; extra == 'all'
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.1; extra == 'all'
 Requires-Dist: opentelemetry-sdk>=1.39.1; extra == 'all'
+Requires-Dist: uvicorn>=0.42.0; extra == 'all'
 Provides-Extra: azureopenai
 Requires-Dist: azure-identity>=1.25.1; extra == 'azureopenai'
 Requires-Dist: openai>=1.107.1; extra == 'azureopenai'
@@ -28,20 +30,44 @@ Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.39.1; extra == 'otel'
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.1; extra == 'otel'
 Requires-Dist: opentelemetry-sdk>=1.39.1; extra == 'otel'
+Provides-Extra: webui
+Requires-Dist: fastapi>=0.135.2; extra == 'webui'
+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.3.2/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.2/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.3.5**
+Current release: **0.4.2**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
+## What's New in 0.4.2
+
+- Rebased the WebUI source frontend on the picoagents frontend snapshot copied into `src/agentbyte/webui/frontend/`.
+- Added the packaged picoagents-style `agent_framework_devui` assets under `src/agentbyte/webui/` for parity/reference work.
+- Fixed wheel packaging so the bundled WebUI assets are included once, unblocking PyPI publish.
+
+## What's New in 0.4.1
+
+- Extended `EmbeddingResult` with a single-vector `embedding` field while preserving `embeddings`, `usage`, `model`, and `metadata`.
+- Updated OpenAI and Azure embedding clients so single-input calls are easier to consume without losing batch compatibility.
+- Added and validated focused embedding client coverage for the new dual-field result contract.
+
+## What's New in 0.4.0
+
+- Added multi-agent orchestration foundations with `BaseOrchestrator`.
+- Added `RoundRobinOrchestrator`, `AIOrchestrator`, and `PlanBasedOrchestrator`.
+- Added a full termination system for autonomous orchestration flows.
+- Added plan-based orchestration examples, tests, and study/tutorial docs.
+- Expanded OpenTelemetry coverage across agents, workflows, and orchestration roots with aggregate usage summaries.
+- Added a packaged Chapter 8 WebUI with FastAPI + SSE, session handling, discovery, and a browser UI for agents, workflows, and orchestrators.
+
 ## What's New in 0.3.5
 
 - Added first-class async embeddings clients in `agentbyte.llm` for OpenAI and Azure OpenAI.
@@ -124,6 +150,7 @@ Optional extras:
 uv sync --extra openai
 uv sync --extra azureopenai
 uv sync --extra otel
+uv sync --extra webui
 ```
 
 ### Install in another project (pip / uv add)
@@ -138,6 +165,14 @@ pip install "agentbyte[azureopenai,otel]"
 uv add "agentbyte[azureopenai,otel]"
 ```
 
+For the browser WebUI:
+
+```bash
+pip install "agentbyte[webui]"
+# or
+uv add "agentbyte[webui]"
+```
+
 Install all optional features:
 
 ```bash
@@ -173,6 +208,111 @@ agent = Agent(
 )
 ```
 
+## Run The WebUI
+
+### Option 1: Run the included demo app
+
+This is the easiest way to see the WebUI working end to end with:
+- one demo agent
+- one demo workflow
+- one demo orchestrator
+
+Step 1. Install the WebUI extra:
+
+```bash
+uv sync --extra webui
+```
+
+Step 2. Start the demo app:
+
+```bash
+uv run python examples/webui/basic_webui.py
+```
+
+Step 3. Open the browser:
+
+```text
+http://127.0.0.1:8080
+```
+
+If auto-open is enabled in your environment, the browser may open automatically.
+
+### Option 2: Run the WebUI against your current project directory
+
+Use this when you want Agentbyte to scan a directory for exported `agent`, `workflow`, or `orchestrator` objects.
+
+Important: discovery is convention-based. The scanned directory must contain Python modules that expose top-level variables literally named `agent`, `workflow`, or `orchestrator`. If you point `--dir` at a folder that does not export those names, the UI will load but show `No entities found`.
+
+Step 1. Install the WebUI extra:
+
+```bash
+uv sync --extra webui
+```
+
+Step 2. Launch the WebUI and scan the current directory:
+
+```bash
+uv run agentbyte webui --dir .
+```
+
+Step 3. Open the browser:
+
+```text
+http://127.0.0.1:8080
+```
+
+Useful variants:
+
+```bash
+uv run agentbyte webui --dir . --port 8080 --host 127.0.0.1 --no-open
+uv run agentbyte webui --dir examples --port 8090
+```
+
+For this repository, the most reliable first-run path is still the bundled demo:
+
+```bash
+uv run python examples/webui/basic_webui.py
+```
+
+Use `agentbyte webui --dir ...` when you have a directory of exportable demo modules, for example:
+
+```python
+# my_entities.py
+agent = ...
+workflow = ...
+orchestrator = ...
+```
+
+### Option 3: Run it programmatically
+
+Use this when you want to serve in-memory entities directly from Python.
+
+```python
+from agentbyte.webui import serve
+
+serve(entities=[agent], port=8080, auto_open=True)
+```
+
+### Quick Troubleshooting
+
+If the app does not start:
+
+```bash
+uv sync --extra webui
+```
+
+If port `8080` is already in use:
+
+```bash
+uv run agentbyte webui --dir . --port 8090
+```
+
+If you do not want the browser to open automatically:
+
+```bash
+uv run agentbyte webui --dir . --no-open
+```
+
 ## Project Layout
 
 ```
@@ -202,4 +342,3 @@ MIT — see [LICENSE](LICENSE).
 
 - [Designing Multi-Agent Systems](https://github.com/victordibia/designing-multiagent-systems/tree/main)
 - [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)
-