agentbyte 0.3.2__tar.gz → 0.3.6__tar.gz

agentbyte-0.3.6/.github/skills/agentbyte-llm-client/SKILL.md

@@ -0,0 +1,127 @@
+````skill
+---
+name: agentbyte-llm-client
+description: Guide for initializing Agentbyte chat and embedding clients for OpenAI/Azure OpenAI. Use this when setting up authentication, provider fallback, or validating usage/cost metadata from results.
+---
+
+Use this skill when a user needs to initialize Agentbyte model clients (`OpenAI*` / `AzureOpenAI*`) for either chat completion or embeddings.
+
+## Supported client families
+
+- **Chat:** `OpenAIChatCompletionClient`, `AzureOpenAIChatCompletionClient`
+- **Embeddings:** `OpenAIEmbeddingClient`, `AzureOpenAIEmbeddingClient`
+
+## Core Patterns
+
+### 1. OpenAI Chat Client Initialization
+
+#### Method A: Env-based factory (Recommended)
+```python
+from agentbyte.llm.openai import OpenAIChatCompletionClient
+
+model_client = OpenAIChatCompletionClient.from_api_key(
+    model="gpt-4o",
+    config={"max_completion_tokens": 500},
+)
+```
+
+#### Method B: Direct Dependency Injection
+```python
+import os
+from openai import AsyncOpenAI
+from agentbyte.llm.openai import OpenAIChatCompletionClient
+
+raw_client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"], timeout=30.0)
+model_client = OpenAIChatCompletionClient(model="gpt-4o", client=raw_client)
+```
+
+### 2. Azure OpenAI Chat Client Initialization
+
+#### Method A: Managed Identity (Azure-hosted production)
+```python
+from agentbyte.llm.azure_openai import AzureOpenAIChatCompletionClient
+
+model_client = AzureOpenAIChatCompletionClient.from_default_credential(
+    model="gpt-4o-mini"
+)
+```
+
+#### Method B: Certificate Auth (Service Principal)
+```python
+import os
+from agentbyte.llm.azure_openai import AzureOpenAIChatCompletionClient
+
+model_client = AzureOpenAIChatCompletionClient.from_certificate(
+    model="gpt-4o-mini",
+    tenant_id=os.environ["AZURE_TENANT_ID"],
+    client_id=os.environ["AZURE_CLIENT_ID"],
+    certificate_data=os.environ["AZURE_CERT_DATA"],
+)
+```
+
+### 3. Embedding Client Initialization (single-provider fallback)
+
+```python
+import os
+from agentbyte.llm import OpenAIEmbeddingClient, AzureOpenAIEmbeddingClient
+
+
+def build_embedding_client():
+    if os.getenv("OPENAI_API_KEY"):
+        return (
+            "openai",
+            OpenAIEmbeddingClient.from_api_key(
+                model="text-embedding-3-small",
+                config={"encoding_format": "float"},
+            ),
+        )
+
+    model = os.getenv("AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME")
+    if not model:
+        raise ValueError(
+            "Set OPENAI_API_KEY or AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME to build an embedding client."
+        )
+
+    if os.getenv("AZURE_OPENAI_API_KEY"):
+        return (
+            "azure-openai",
+            AzureOpenAIEmbeddingClient.from_api_key(
+                model=model,
+                api_version=os.getenv("AZURE_OPENAI_API_VERSION", "2024-10-21"),
+            ),
+        )
+
+    return (
+        "azure-openai",
+        AzureOpenAIEmbeddingClient.from_certificate(
+            model=model,
+            api_version=os.getenv("AZURE_OPENAI_API_VERSION", "2024-10-21"),
+        ),
+    )
+
+
+provider, embedding_client = build_embedding_client()
+```
+
+### 4. Embedding result usage (current API)
+
+```python
+result = await embedding_client.create_batch(["alpha", "beta"])
+
+vectors = result.embeddings
+tokens = result.usage.tokens_input
+cost = result.usage.cost_estimate
+```
+
+`create(...)` and `create_batch(...)` return `EmbeddingResult`.
+
+## 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`.
+- **Cost precision:** `usage.cost_estimate` is rounded to 15 decimals; tiny single-call embedding costs can still be very small.
+
+````

agentbyte-0.3.6/.github/skills/agentbyte-middleware/SKILL.md

@@ -0,0 +1,75 @@
+````skill
+---
+name: agentbyte-middleware
+description: Guide for adding middleware chains in Agentbyte for agent and embedding operations. Use this for logging, guardrails, PII redaction, usage tracking, and tracing.
+---
+
+Use this skill when you need to intercept operations via `MiddlewareChain` and `BaseMiddleware`.
+
+## Pattern: Custom Middleware (current interface)
+
+```python
+from typing import Any, Optional
+
+from agentbyte.middleware import BaseMiddleware, MiddlewareContext
+
+
+class MyLogger(BaseMiddleware):
+    async def process_request(self, context: MiddlewareContext) -> MiddlewareContext:
+        print(f"request: {context.operation} ({context.agent_name})")
+        return context
+
+    async def process_response(self, context: MiddlewareContext, result: Any) -> Any:
+        print(f"response: {context.operation} ({context.agent_name})")
+        return result
+
+    async def process_error(
+        self,
+        context: MiddlewareContext,
+        error: Exception,
+    ) -> Optional[Any]:
+        print(f"error: {context.operation} ({context.agent_name}): {error}")
+        return None
+```
+
+## Where middleware is applied
+
+- **Agent-level:** chat model calls, tool calls, memory access.
+- **Embedding client-level:** embedding requests (`operation="embedding_call"`) in `BaseEmbeddingClient`.
+
+For embeddings, register middleware directly on the client:
+
+```python
+from agentbyte.llm import OpenAIEmbeddingClient
+from agentbyte.middleware import LoggingMiddleware, PIIRedactionMiddleware
+
+client = OpenAIEmbeddingClient.from_api_key(model="text-embedding-3-small")
+client.add_middleware(LoggingMiddleware())
+client.add_middleware(PIIRedactionMiddleware())
+
+result = await client.create("Contact me at demo@example.com")
+```
+
+## Built-in Middlewares
+
+- `LoggingMiddleware`: Emits operation request/response/error logs.
+- `GuardrailMiddleware`: Blocks configured tools and forbidden patterns.
+- `PIIRedactionMiddleware`: Masks common PII patterns in supported payloads.
+- `RateLimitMiddleware`: Applies in-memory throttling.
+- `MetricsMiddleware`: Tracks operation counts, durations, and errors.
+- `OTelMiddleware`: Emits OpenTelemetry traces/metrics when enabled.
+
+## Embedding-specific notes
+
+- `PIIRedactionMiddleware` supports `embedding_call` payload shape: `{"input": [...], "kwargs": {...}}`.
+- Logging output appears at INFO level under logger `agentbyte.middleware`.
+- In notebooks, configure logging first if middleware logs should appear.
+
+## Guardrails
+
+- **Execution order:** `process_request` runs in list order; `process_response` runs in reverse order.
+- **Error handling:** Use `process_error(...)` to recover or propagate failures.
+- **Context contract:** Use `MiddlewareContext` (`operation`, `agent_name`, `agent_context`, `data`, `metadata`) to pass state.
+- **No duplicate registration:** In notebooks, prefer idempotent middleware registration to avoid stacking duplicate handlers across repeated runs.
+
+````

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

@@ -4,6 +4,50 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.3.6] - 2026-03-23
+
+### Added
+- New notebook-focused logging utility: `configure_notebook_logging()` in `agentbyte.notebook`
+  - Simplifies logging setup in Jupyter notebooks
+  - Always shows middleware logs at INFO level for demo visibility
+  - Suppresses noisy HTTP/Azure/OpenAI logs in quiet mode by default
+  - Exported from package root for easy notebook imports
+
+### Changed
+- Azure embedding client authentication simplified in notebook 02c:
+  - Removed API-key auth path (certificate-only for Azure in notebooks)
+  - Kept API-key auth for OpenAI embeddings
+  - Notebook now supports on-the-fly model/API-version overrides
+
+## [0.3.5] - 2026-03-18
+
+### Added
+- New async embeddings client foundation in `agentbyte.llm`:
+	- `BaseEmbeddingClient`, `BaseEmbeddingClientConfig`
+	- `OpenAIEmbeddingClient`, `OpenAIEmbeddingClientConfig`
+	- `AzureOpenAIEmbeddingClient`, `AzureOpenAIEmbeddingClientConfig`
+	- `EmbeddingResult` type export in `agentbyte.llm`.
+- Separate embedding APIs for single and batch generation:
+	- `create(input_text: str) -> list[float]`
+	- `create_batch(input_texts: list[str]) -> list[list[float]]`
+
+### Changed
+- `AzureOpenAISettings` now supports `embedding_deployment_name` from
+	`AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` for embedding client factory resolution.
+
+### Testing
+- Added focused unit tests for OpenAI and Azure embedding clients covering
+	single input, batch ordering, empty input validation, and env-based factory loading.
+
+## [0.3.4] - 2026-03-18
+
+### Changed
+- `AzureServicePrincipalSettings`: replaced `model_post_init` with a `@model_validator(mode="after")` to normalize `cognitive_scope`. All three input forms are handled: bare URL → `/.default` appended; URL ending with `/` → `.default` appended; URL already ending with `/.default` → unchanged.
+
+## [0.3.3] - 2026-03-18
+### Changed
+- `AzureServicePrincipalSettings.model_post_init` now automatically appends `/.default` to `cognitive_scope` if it is not already present (e.g. `https://cognitiveservices.azure.com` → `https://cognitiveservices.azure.com/.default`).
+
 ## [0.3.2] - 2026-03-18
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.3.2
+Version: 0.3.6
 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
@@ -38,10 +38,19 @@ Description-Content-Type: text/markdown
 
 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.2**
+Current release: **0.3.5**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
+## What's New in 0.3.5
+
+- Added first-class async embeddings clients in `agentbyte.llm` for OpenAI and Azure OpenAI.
+- Added separate single/batch embedding methods:
+  - `create(input_text: str) -> list[float]`
+  - `create_batch(input_texts: list[str]) -> list[list[float]]`
+- Added Azure embedding deployment setting support:
+  `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME`.
+
 ## What's New in 0.3.2
 
 - **Python baseline lowered:** package runtime requirement is now **Python 3.11+**.

{agentbyte-0.3.2 → agentbyte-0.3.6}/README.md

@@ -6,10 +6,19 @@
 
 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.2**
+Current release: **0.3.5**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
+## What's New in 0.3.5
+
+- Added first-class async embeddings clients in `agentbyte.llm` for OpenAI and Azure OpenAI.
+- Added separate single/batch embedding methods:
+  - `create(input_text: str) -> list[float]`
+  - `create_batch(input_texts: list[str]) -> list[list[float]]`
+- Added Azure embedding deployment setting support:
+  `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME`.
+
 ## What's New in 0.3.2
 
 - **Python baseline lowered:** package runtime requirement is now **Python 3.11+**.

agentbyte-0.3.6/src/agentbyte/__about__.py

@@ -0,0 +1,2 @@
+__version__ = "0.3.6"
+VERSION = __version__

{agentbyte-0.3.2 → agentbyte-0.3.6}/src/agentbyte/__init__.py

@@ -16,6 +16,7 @@ from agentbyte.__about__ import VERSION
 from agentbyte.agents import Agent
 from agentbyte.entity import Entity
 from agentbyte.middleware import init_auto_instrumentation_from_env
+from agentbyte.notebook import configure_notebook_logging
 from agentbyte.session import BaseSession, InMemorySession, Session
 
 # Auto-instrument with OpenTelemetry if enabled.
@@ -34,4 +35,5 @@ __all__ = [
     "Session",
     "BaseSession",
     "InMemorySession",
+    "configure_notebook_logging",
 ]

{agentbyte-0.3.2 → agentbyte-0.3.6}/src/agentbyte/llm/__init__.py

@@ -31,11 +31,17 @@ from .base import (
     AuthenticationError,
     InvalidRequestError,
 )
+from .embeddings_base import BaseEmbeddingClient, BaseEmbeddingClientConfig
 from .openai import OpenAIChatCompletionClient, OpenAIChatCompletionClientConfig
+from .openai_embedding import OpenAIEmbeddingClient, OpenAIEmbeddingClientConfig
 from .azure_openai import (
     AzureOpenAIChatCompletionClient,
     AzureOpenAIChatCompletionClientConfig,
 )
+from .azure_openai_embedding import (
+    AzureOpenAIEmbeddingClient,
+    AzureOpenAIEmbeddingClientConfig,
+)
 from .auth import (
     get_default_token_provider,
     get_certificate_token_provider,
@@ -58,18 +64,26 @@ from agentbyte.messages import (
 from .types import (
     ChatCompletionChunk,
     ChatCompletionResult,
+    EmbeddingResult,
     ModelClientError,
+    ModelPricing,
 )
 
 __all__ = [
     # Base classes
     "BaseChatCompletionClient",
     "BaseChatCompletionClientConfig",
+    "BaseEmbeddingClient",
+    "BaseEmbeddingClientConfig",
     # Provider implementations
     "OpenAIChatCompletionClient",
     "OpenAIChatCompletionClientConfig",
+    "OpenAIEmbeddingClient",
+    "OpenAIEmbeddingClientConfig",
     "AzureOpenAIChatCompletionClient",
     "AzureOpenAIChatCompletionClientConfig",
+    "AzureOpenAIEmbeddingClient",
+    "AzureOpenAIEmbeddingClientConfig",
     # Authentication utilities
     "get_default_token_provider",
     "get_certificate_token_provider",
@@ -96,4 +110,6 @@ __all__ = [
     "Usage",
     "ChatCompletionResult",
     "ChatCompletionChunk",
+    "EmbeddingResult",
+    "ModelPricing",
 ]

{agentbyte-0.3.2 → agentbyte-0.3.6}/src/agentbyte/llm/azure_openai.py

@@ -81,9 +81,11 @@ from .base import (
     AuthenticationError,
     InvalidRequestError,
 )
+from .pricing import PricingRegistry
 from .types import (
     ChatCompletionChunk,
     ChatCompletionResult,
+    ModelPricing,
     ModelClientError,
     Usage,
 )
@@ -168,6 +170,7 @@ class AzureOpenAIChatCompletionClient(
         model: str,
         client: AsyncAzureOpenAI,
         config: Optional[Dict[str, Any]] = None,
+        model_pricing: Optional[ModelPricing] = None,
         max_retries: int = 3,
         initial_retry_delay: float = 1.0,
         max_retry_delay: float = 60.0,
@@ -240,7 +243,7 @@ class AzureOpenAIChatCompletionClient(
             ... )
         """
         super().__init__(model, client, config)
-
+        self.model_pricing = model_pricing
         self.max_retries = max_retries
         self.initial_retry_delay = initial_retry_delay
         self.max_retry_delay = max_retry_delay
@@ -255,6 +258,7 @@ class AzureOpenAIChatCompletionClient(
         api_key: Optional[str] = None,
         service_settings: Optional[Any] = None,
         config: Optional[Dict[str, Any]] = None,
+        model_pricing: Optional[ModelPricing] = None,
         max_retries: int = 3,
         initial_retry_delay: float = 1.0,
         max_retry_delay: float = 60.0,
@@ -334,6 +338,7 @@ class AzureOpenAIChatCompletionClient(
             model=resolved_model,
             client=azure_client,
             config=config,
+            model_pricing=model_pricing,
             max_retries=max_retries,
             initial_retry_delay=initial_retry_delay,
             max_retry_delay=max_retry_delay,
@@ -347,6 +352,7 @@ class AzureOpenAIChatCompletionClient(
         service_settings: Optional[Any] = None,
         scope: str = "https://cognitiveservices.azure.com/.default",
         config: Optional[Dict[str, Any]] = None,
+        model_pricing: Optional[ModelPricing] = None,
         max_retries: int = 3,
         initial_retry_delay: float = 1.0,
         max_retry_delay: float = 60.0,
@@ -431,6 +437,7 @@ class AzureOpenAIChatCompletionClient(
             model=resolved_model,
             client=azure_client,
             config=config,
+            model_pricing=model_pricing,
             max_retries=max_retries,
             initial_retry_delay=initial_retry_delay,
             max_retry_delay=max_retry_delay,
@@ -445,6 +452,7 @@ class AzureOpenAIChatCompletionClient(
         principal_settings: Optional[Any] = None,
         scope: Optional[str] = None,
         config: Optional[Dict[str, Any]] = None,
+        model_pricing: Optional[ModelPricing] = None,
         max_retries: int = 3,
         initial_retry_delay: float = 1.0,
         max_retry_delay: float = 60.0,
@@ -535,6 +543,7 @@ class AzureOpenAIChatCompletionClient(
             model=resolved_model,
             client=azure_client,
             config=config,
+            model_pricing=model_pricing,
             max_retries=max_retries,
             initial_retry_delay=initial_retry_delay,
             max_retry_delay=max_retry_delay,
@@ -548,6 +557,7 @@ class AzureOpenAIChatCompletionClient(
         api_version: Optional[str] = None,
         service_settings: Optional[Any] = None,
         config: Optional[Dict[str, Any]] = None,
+        model_pricing: Optional[ModelPricing] = None,
         max_retries: int = 3,
         initial_retry_delay: float = 1.0,
         max_retry_delay: float = 60.0,
@@ -623,6 +633,7 @@ class AzureOpenAIChatCompletionClient(
             model=resolved_model,
             client=azure_client,
             config=config,
+            model_pricing=model_pricing,
             max_retries=max_retries,
             initial_retry_delay=initial_retry_delay,
             max_retry_delay=max_retry_delay,
@@ -1140,46 +1151,21 @@ class AzureOpenAIChatCompletionClient(
         Returns:
             Estimated cost in USD
 
-        Azure Model Pricing (as of 2024):
-            - GPT-4o: $0.005 per 1K input tokens, $0.015 per 1K output tokens
-            - GPT-4 Turbo: $0.01 per 1K input tokens, $0.03 per 1K output tokens
-            - GPT-4: $0.03 per 1K input tokens, $0.06 per 1K output tokens
-            - GPT-3.5 Turbo: $0.0005 per 1K input tokens, $0.0015 per 1K output tokens
-            - Falls back to GPT-4 pricing for unknown models
+        Pricing is resolved from PricingRegistry for Azure OpenAI; user-provided pricing always takes precedence.
+        Unknown models trigger a warning and fall back to GPT-4 pricing.
 
         Note:
             Azure pricing is typically lower than standard OpenAI pricing.
             For production, validate pricing against your Azure account.
         """
-        # Model pricing mapping (per 1M tokens) - Azure rates
-        pricing = {
-            "gpt-4.1-mini": {"input_per_1m": 0.40, "output_per_1m": 1.60},
-            "gpt-4o-mini": {"input_per_1m": 0.15, "output_per_1m": 0.60},
-            "gpt-4": {"input_per_1m": 30.0, "output_per_1m": 60.0},  # $0.03/$0.06 per 1K
-            "gpt-4-turbo": {"input_per_1m": 10.0, "output_per_1m": 30.0},  # $0.01/$0.03 per 1K
-            "gpt-3.5-turbo": {"input_per_1m": 0.50, "output_per_1m": 1.50},
-            "gpt-4.1": {"input_per_1m": 2.0, "output_per_1m": 8.0},
-            "gpt-4.1-nano": {"input_per_1m": 0.10, "output_per_1m": 0.40},
-            "gpt-5-mini": {"input_per_1m": 0.25, "output_per_1m": 2.0},
-            "gpt-5.1-chat": {"input_per_1m": 1.25, "output_per_1m": 10.0}
-            }
-
-        # Find matching pricing; try to match model name prefix
-        model_pricing = None
-        for model_key, pricing_data in pricing.items():
-            if model_key in self.model.lower():
-                model_pricing = pricing_data
-                break
-
-        # Default to GPT-4 pricing if no match found
-        if not model_pricing:
-            model_pricing = pricing["gpt-4"]
-
-        # Calculate cost in USD
-        input_cost = (prompt_tokens / 1_000_000) * model_pricing["input_per_1m"]
-        output_cost = (completion_tokens / 1_000_000) * model_pricing["output_per_1m"]
+        # User-provided pricing always takes precedence
+        if self.model_pricing is not None:
+            pricing = self.model_pricing
+        else:
+            # Resolve from registry (warns if not found, uses default GPT-4 pricing)
+            pricing = PricingRegistry.resolve_azure_chat_pricing(self.model)
 
-        return round(input_cost + output_cost, 6)
+        return pricing.calculate_cost(prompt_tokens, completion_tokens)
 
     def _to_config(self) -> AzureOpenAIChatCompletionClientConfig:
         """Serialize to config. Env-var names are stored; secrets are never written."""