agentbyte 0.4.0__tar.gz → 0.4.2__tar.gz

{agentbyte-0.4.0 → 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.4.0 → agentbyte-0.4.2}/CHANGELOG.md

@@ -4,6 +4,31 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.4.0
+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,35 @@ 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.4.0/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.4.0**
+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`.
@@ -49,6 +66,7 @@ Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyni
 - 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
 
@@ -132,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)
@@ -146,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
@@ -181,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
 
 ```

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

@@ -1,15 +1,27 @@
 <p align="center">
-  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.4.0/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.4.0**
+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`.
@@ -17,6 +29,7 @@ Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyni
 - 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
 
@@ -100,6 +113,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)
@@ -114,6 +128,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
@@ -149,6 +171,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
 
 ```

{agentbyte-0.4.0 → agentbyte-0.4.2}/pyproject.toml

@@ -35,14 +35,21 @@ azureopenai = [
     "openai>=1.107.1",
     "azure-identity>=1.25.1",
 ]
+webui = [
+    "fastapi>=0.135.2",
+    "uvicorn>=0.42.0",
+]
 all = [
     "openai>=1.107.1",
     "azure-identity>=1.25.1",
     "opentelemetry-api>=1.39.1",
     "opentelemetry-exporter-otlp-proto-http>=1.39.1",
     "opentelemetry-sdk>=1.39.1",
+    "fastapi>=0.135.2",
+    "uvicorn>=0.42.0",
 ]
 
+
 [project.scripts]
 agentbyte = "agentbyte.cli:main"
 
@@ -60,7 +67,7 @@ packages = ["src/agentbyte"]
 ".github/skills" = "agentbyte/skills"
 
 [tool.hatch.build.targets.sdist]
-include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md", "/.github/skills"]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md", "/.github/skills", "/src/agentbyte/webui/ui"]
 
 [dependency-groups]
 dev = [
@@ -84,6 +91,10 @@ test = [
 viz = [
     "graphviz>=0.21",
 ]
+webui = [
+    "fastapi>=0.135.2",
+    "uvicorn>=0.42.0",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

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

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

{agentbyte-0.4.0 → agentbyte-0.4.2}/src/agentbyte/__init__.py

@@ -47,6 +47,7 @@ from agentbyte.termination import (
     TimeoutTermination,
     TokenUsageTermination,
 )
+from agentbyte.webui import WebUIServer, create_app, serve
 
 # Auto-instrument with OpenTelemetry if enabled.
 # Must be set BEFORE importing agentbyte for transparent instrumentation.
@@ -90,4 +91,8 @@ __all__ = [
     "ExternalTermination",
     "CancellationTermination",
     "CompositeTermination",
+    # WebUI
+    "WebUIServer",
+    "create_app",
+    "serve",
 ]

{agentbyte-0.4.0 → agentbyte-0.4.2}/src/agentbyte/cli/main.py

@@ -137,9 +137,42 @@ def cmd_create_skills(args: argparse.Namespace, cwd: Path | None = None) -> int:
 
 _COMMANDS = [
     ("create-skills", "Copy AI assistant skills into this project"),
+    ("webui", "Launch the Agentbyte WebUI"),
 ]
 
 
+def cmd_webui(args: argparse.Namespace) -> int:
+    """Implement the webui sub-command."""
+    try:
+        from agentbyte.webui import launch
+    except Exception as exc:
+        print(
+            "Error: WebUI dependencies are not available. "
+            "Install them with `uv sync --extra webui` or `pip install agentbyte[webui]`.",
+            file=sys.stderr,
+        )
+        print(f"Details: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        launch(
+            entities_dir=args.dir,
+            port=args.port,
+            host=args.host,
+            auto_open=not args.no_open,
+            reload=args.reload,
+            log_level=args.log_level,
+        )
+    except KeyboardInterrupt:
+        print("\nShutting down Agentbyte WebUI.")
+        return 0
+    except Exception as exc:
+        print(f"Error starting Agentbyte WebUI: {exc}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
 def _prompt_choice(prompt: str, choices: list[str], default: int = 1) -> str | None:
     """Print a numbered menu and return the selected string value.
 
@@ -203,6 +236,17 @@ def _interactive_wizard() -> int:
         args = argparse.Namespace(provider=provider)
         return cmd_create_skills(args)
 
+    if command == "webui":
+        args = argparse.Namespace(
+            dir=".",
+            port=8080,
+            host="127.0.0.1",
+            no_open=False,
+            reload=False,
+            log_level="info",
+        )
+        return cmd_webui(args)
+
     return 0
 
 
@@ -240,6 +284,44 @@ def _build_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    webui_parser = subparsers.add_parser(
+        "webui",
+        help="Launch the packaged Agentbyte WebUI",
+    )
+    webui_parser.add_argument(
+        "--dir",
+        default=".",
+        help="Directory to scan for agents, workflows, and orchestrators",
+    )
+    webui_parser.add_argument(
+        "--port",
+        "-p",
+        type=int,
+        default=8080,
+        help="Port to run the server on (default: 8080)",
+    )
+    webui_parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind the server to (default: 127.0.0.1)",
+    )
+    webui_parser.add_argument(
+        "--no-open",
+        action="store_true",
+        help="Do not automatically open the browser",
+    )
+    webui_parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload for development",
+    )
+    webui_parser.add_argument(
+        "--log-level",
+        choices=["debug", "info", "warning", "error"],
+        default="info",
+        help="Server log level (default: info)",
+    )
+
     return parser
 
 
@@ -257,7 +339,8 @@ def main() -> None:
 
     if args.command == "create-skills":
         sys.exit(cmd_create_skills(args))
+    if args.command == "webui":
+        sys.exit(cmd_webui(args))
 
     parser.print_help()
     sys.exit(1)
-

{agentbyte-0.4.0 → agentbyte-0.4.2}/src/agentbyte/llm/azure_openai_embedding.py

@@ -398,6 +398,7 @@ class AzureOpenAIEmbeddingClient(
             )
 
             return EmbeddingResult(
+                embedding=vectors[0],
                 embeddings=vectors,
                 model=getattr(response, "model", self.model),
                 usage=usage,

{agentbyte-0.4.0 → agentbyte-0.4.2}/src/agentbyte/llm/embeddings_base.py

@@ -50,7 +50,11 @@ class BaseEmbeddingClient(ABC, ComponentLoader):
 
     @abstractmethod
     async def create(self, input_text: str, **kwargs: Any) -> EmbeddingResult:
-        """Create one embedding result from one text input."""
+        """Create one embedding result from one text input.
+
+        Consumers should read `result.embedding` for the single returned vector.
+        The batch-oriented `result.embeddings` field still contains one item.
+        """
 
     @abstractmethod
     async def create_batch(
@@ -58,7 +62,11 @@ class BaseEmbeddingClient(ABC, ComponentLoader):
         input_texts: List[str],
         **kwargs: Any,
     ) -> EmbeddingResult:
-        """Create one embedding result from a batch of text inputs."""
+        """Create one embedding result from a batch of text inputs.
+
+        Consumers should read `result.embeddings` for the full batch in request
+        order. The `result.embedding` field mirrors the first vector.
+        """
 
     async def _execute_embedding_operation(
         self,

{agentbyte-0.4.0 → agentbyte-0.4.2}/src/agentbyte/llm/openai_embedding.py

@@ -178,6 +178,7 @@ class OpenAIEmbeddingClient(
             )
 
             return EmbeddingResult(
+                embedding=vectors[0],
                 embeddings=vectors,
                 model=getattr(response, "model", self.model),
                 usage=usage,

{agentbyte-0.4.0 → agentbyte-0.4.2}/src/agentbyte/llm/types.py

@@ -158,12 +158,25 @@ class EmbeddingResult(BaseModel):
     Response payload for embedding generation.
 
     Attributes:
+        embedding: First embedding vector in request order. For single-input
+            calls, this is the embedding for the provided text.
         embeddings: Embedding vectors in request order.
         model: Model/deployment used by the provider.
         usage: Token usage and execution metadata.
         metadata: Provider-specific metadata.
+
+    Invariant:
+        `embedding == embeddings[0]`
+
+        Single-input `create()` calls return exactly one vector in
+        `embeddings`, while batch `create_batch()` calls return all vectors in
+        request order and expose the first vector through `embedding`.
     """
 
+    embedding: list[float] = Field(
+        ...,
+        description="First embedding vector in request order",
+    )
     embeddings: list[list[float]] = Field(
         ...,
         description="Embedding vectors in request order",
@@ -212,4 +225,3 @@ __all__ = [
     "ModelClientError",
 ]
 
-