yera 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

infra_mvp/base_client.py

@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base_server import BaseServer
+
+
+class BaseClient(ABC):
+    def __init__(self, url_base: str):
+        self.url_base = url_base
+
+    def _make_url(self, *parts: str) -> str:
+        return "/".join([self.url_base.rstrip("/"), *list(parts)])
+
+    @classmethod
+    @abstractmethod
+    def from_server(cls, server: "BaseServer") -> "BaseClient":
+        """Create client from server instance.
+
+        Must be implemented by each subclass with appropriate server type.
+
+        Args:
+            server: BaseServer instance to connect to
+
+        Returns:
+            BaseClient configured to connect to the server
+
+        """
+        raise NotImplementedError

infra_mvp/base_server.py

@@ -0,0 +1,68 @@
+from abc import ABC, abstractmethod
+from threading import Thread
+from time import sleep
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from uvicorn import Config, Server
+
+from yera.config.logging import LOG_CONFIG
+
+
+class BaseServer(Server, ABC):
+    def __init__(self, host: str | None = "127.0.0.1", port: int | None = 8989):
+        self.host = host
+        self.port = port
+        self.thread = None
+        app = self.build_api()
+        app = self._add_middleware(app)
+
+        # Expose the fully configured FastAPI app (including middleware such as CORS)
+        # so that external runners (e.g. uvicorn infra_mvp.stream.app:app) can
+        # reuse the same application instance.
+        self.app: FastAPI = app
+
+        super().__init__(Config(self.app, self.host, self.port, log_config=LOG_CONFIG))
+
+    @property
+    def url_base(self):
+        return f"http://{self.host}:{self.port}"
+
+    @abstractmethod
+    def build_api(self) -> FastAPI:
+        pass
+
+    def _add_middleware(self, app: FastAPI) -> FastAPI:
+        # Add CORS middleware for local development - enables Postman testing and future web frontends
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],  # Allow all origins for local development
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+        return app
+
+    def start(self):
+        self.thread = Thread(target=self.run)
+        self.thread.start()
+        while not self.started:
+            if not self.thread.is_alive():
+                raise RuntimeError("Server failed to start")
+            sleep(0.1)
+
+        # If port was 0 (random), update it with the actual bound port
+        if self.port == 0:
+            # Update port with the actual bound port from the first socket
+            self.port = self.servers[0].sockets[0].getsockname()[1]
+
+    def stop(self):
+        self.should_exit = True
+        self.thread.join()
+
+    def __enter__(self) -> "BaseServer":
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.stop()

infra_mvp/monitoring/__init__.py

@@ -0,0 +1,15 @@
+"""Monitoring and metrics utilities for Yera services."""
+
+from .metrics import (
+    ServiceMetrics,
+    get_metrics_endpoint,
+    track_operation,
+    track_request,
+)
+
+__all__ = [
+    "ServiceMetrics",
+    "get_metrics_endpoint",
+    "track_operation",
+    "track_request",
+]

infra_mvp/monitoring/metrics.py

@@ -0,0 +1,185 @@
+"""Prometheus metrics integration for Yera services."""
+
+import time
+from collections.abc import Callable
+from contextlib import contextmanager
+from functools import wraps
+from typing import Any
+
+from fastapi import Response
+from prometheus_client import (
+    CONTENT_TYPE_LATEST,
+    CollectorRegistry,
+    Counter,
+    Gauge,
+    Histogram,
+    generate_latest,
+)
+
+
+class ServiceMetrics:
+    """Prometheus metrics for a Yera service."""
+
+    def __init__(self, service_name: str, registry: CollectorRegistry | None = None):
+        """Initialize metrics for a service.
+
+        Args:
+            service_name: Name of the service (e.g., 'api', 'iam', 'stream')
+            registry: Prometheus registry to use. If None, creates a new isolated registry.
+
+        """
+        self.service_name = service_name
+        self.registry = registry or CollectorRegistry()
+        prefix = f"{service_name}_"
+
+        # Request metrics
+        self.requests_total = Counter(
+            f"{prefix}requests_total",
+            f"Total number of {service_name} API requests",
+            ["endpoint", "method", "status"],
+            registry=self.registry,
+        )
+
+        self.request_duration_seconds = Histogram(
+            f"{prefix}request_duration_seconds",
+            f"Duration of {service_name} API requests",
+            ["endpoint", "method"],
+            buckets=[0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0],
+            registry=self.registry,
+        )
+
+        # Error metrics
+        self.errors_total = Counter(
+            f"{prefix}errors_total",
+            f"Total number of {service_name} errors",
+            ["operation", "error_type"],
+            registry=self.registry,
+        )
+
+        # Resource gauges (optional, can be extended)
+        self._gauges: dict[str, Gauge] = {}
+
+    def create_gauge(
+        self, name: str, description: str, labels: list[str] | None = None
+    ) -> Gauge:
+        """Create a custom gauge metric."""
+        full_name = f"{self.service_name}_{name}"
+        if full_name in self._gauges:
+            return self._gauges[full_name]
+
+        gauge = Gauge(full_name, description, labels or [], registry=self.registry)
+        self._gauges[full_name] = gauge
+        return gauge
+
+    def create_counter(
+        self, name: str, description: str, labels: list[str] | None = None
+    ) -> Counter:
+        """Create a custom counter metric."""
+        full_name = f"{self.service_name}_{name}"
+        return Counter(full_name, description, labels or [], registry=self.registry)
+
+    def create_histogram(
+        self,
+        name: str,
+        description: str,
+        labels: list[str] | None = None,
+        buckets: list[float] | None = None,
+    ) -> Histogram:
+        """Create a custom histogram metric."""
+        full_name = f"{self.service_name}_{name}"
+        return Histogram(
+            full_name,
+            description,
+            labels or [],
+            buckets=buckets,
+            registry=self.registry,
+        )
+
+    def track_request(
+        self,
+        endpoint: str,
+        method: str,
+        status_code: int,
+        duration: float | None = None,
+    ):
+        """Track an API request."""
+        self.requests_total.labels(
+            endpoint=endpoint, method=method, status=str(status_code)
+        ).inc()
+        if duration is not None:
+            self.request_duration_seconds.labels(
+                endpoint=endpoint, method=method
+            ).observe(duration)
+
+    def track_error(self, operation: str, error_type: str):
+        """Track an error."""
+        self.errors_total.labels(operation=operation, error_type=error_type).inc()
+
+    @contextmanager
+    def track_operation_time(self, endpoint: str, method: str):
+        """Context manager to track operation duration."""
+        start_time = time.time()
+        try:
+            yield
+        finally:
+            duration = time.time() - start_time
+            self.request_duration_seconds.labels(
+                endpoint=endpoint, method=method
+            ).observe(duration)
+
+
+# Decorator for tracking requests
+def track_request(metrics: ServiceMetrics, endpoint: str, method: str = "POST"):
+    """Decorator to track request metrics."""
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            start_time = time.time()
+            status_code = 200
+            try:
+                result = await func(*args, **kwargs)
+                return result
+            except Exception as e:
+                if hasattr(e, "status_code"):
+                    status_code = e.status_code
+                else:
+                    status_code = 500
+                raise
+            finally:
+                duration = time.time() - start_time
+                metrics.track_request(endpoint, method, status_code, duration)
+
+        return wrapper
+
+    return decorator
+
+
+# Context manager for tracking operations
+@contextmanager
+def track_operation(metrics: ServiceMetrics, operation: str):
+    """Context manager to track operation execution."""
+    try:
+        yield
+    except Exception as e:
+        error_type = type(e).__name__
+        metrics.track_error(operation, error_type)
+        raise
+
+
+# Metrics endpoint generator
+def get_metrics_endpoint(metrics: ServiceMetrics):
+    """Get a FastAPI endpoint function for /metrics.
+
+    Args:
+        metrics: ServiceMetrics instance with the registry to use
+
+    """
+
+    async def metrics_endpoint() -> Response:
+        """Prometheus metrics endpoint."""
+        return Response(
+            content=generate_latest(metrics.registry), media_type=CONTENT_TYPE_LATEST
+        )
+
+    return metrics_endpoint

infra_mvp/stream/README.md

@@ -0,0 +1,56 @@
+# Yera Stream Test Server
+
+A minimal FastAPI-based server that streams predefined conversations over Server-Sent Events (SSE) for the Yera UI.
+
+## Running the Server
+
+### Simple start (no auto-reload)
+
+```bash
+uv run python -m infra_mvp.stream --host 127.0.0.1 --port 8991
+```
+
+### Development mode (with auto-reload)
+
+```bash
+uv run uvicorn infra_mvp.stream.app:app --host 0.0.0.0 --port 8991 --reload
+```
+
+The development command is recommended while working on the UI or stream conversations, as it automatically restarts when code changes.
+
+## Key Endpoints
+
+- `POST /api/session` – create a new streaming session for a given `conversation_id`
+- `GET /api/stream?session_id=...` – stream conversation messages via SSE
+- `POST /api/interaction?session_id=...` – send user interactions (buttons, input prompts, etc.)
+- `GET /health` – simple health check
+
+## Conversations
+
+By default, the server loads conversation JSON files from:
+
+```text
+src/infra_mvp/stream/conversations/
+```
+
+The integration tests use separate, test-only conversations under:
+
+```text
+tests/integration/infra_mvp/stream/conversations/
+```
+
+## Testing
+
+```bash
+uv run pytest tests/integration/infra_mvp/stream -q
+```
+
+This runs fast, focused integration tests against the stream server.
+
+For lower-level checks of data loading and helpers, you can also run the unit tests:
+
+```bash
+uv run pytest tests/unit/infra_mvp/stream -q
+```
+
+

infra_mvp/stream/__init__.py

@@ -0,0 +1,14 @@
+"""Stream server module for SSE-based message streaming.
+
+This module provides a standalone server for UI development and testing.
+The streaming functionality will eventually be integrated into the main ApiServer.
+"""
+
+from .container import create_container, create_stream_server
+from .server import StreamServer
+
+__all__ = [
+    "StreamServer",
+    "create_container",
+    "create_stream_server",
+]

infra_mvp/stream/__main__.py

@@ -0,0 +1,101 @@
+"""Main entry point for running StreamServer.
+
+Usage:
+    python -m infra_mvp.stream --agent-path demos/agents/basic_chatbot.py
+    python -m infra_mvp.stream --agent-path demos/agents/basic_chatbot.py --port 8991
+    python -m infra_mvp.stream --agent-path demos/agents/basic_chatbot.py --host 0.0.0.0 --port 8991
+"""
+
+import argparse
+import os
+import signal
+import sys
+from pathlib import Path
+
+from infra_mvp.stream.container import create_stream_server
+from yera.agents.discovery import load_agent
+
+
+def main():
+    """Run StreamServer with command-line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Start StreamServer for SSE streaming to Yera UI"
+    )
+    default_host = os.getenv("HOST", "0.0.0.0")
+    default_port = int(os.getenv("PORT", "8991"))
+
+    parser.add_argument(
+        "--agent-path",
+        type=str,
+        required=True,
+        help="Path to Python file containing an agent",
+    )
+    parser.add_argument(
+        "--agent",
+        type=str,
+        default=None,
+        help="Name of the agent to use when multiple agents exist in the file",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default=default_host,
+        help=f"Server host address (default: {default_host})",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=default_port,
+        help=f"Server port number (default: {default_port})",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging of events to file (logs to yera-debug-<timestamp>.jsonl)",
+    )
+
+    args = parser.parse_args()
+
+    # Load Python agent
+    try:
+        agent_wrapper = load_agent(Path(args.agent_path), agent_name=args.agent)
+    except (FileNotFoundError, ValueError) as e:
+        print(f"Error loading agent: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Create stream server with Python agent
+    server = create_stream_server(
+        agent=agent_wrapper,
+        host=args.host,
+        port=args.port,
+        debug=args.debug,
+    )
+
+    # Handle graceful shutdown
+    def signal_handler(sig, frame):  # noqa: ARG001
+        print("\nShutting down server...")
+        server.stop()
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+
+    # Start server
+    print(f"Starting StreamServer on {server.url_base}")
+    print("Press Ctrl+C to stop the server")
+    print(f"Health check: {server.url_base}/health")
+    print(f"API docs: {server.url_base}/docs")
+
+    try:
+        with server:
+            # Keep server running
+            import time
+
+            while True:
+                time.sleep(1)
+    except KeyboardInterrupt:
+        signal_handler(None, None)
+
+
+if __name__ == "__main__":
+    main()

infra_mvp/stream/agents/demos/financial/chart_additions_plan.md

@@ -0,0 +1,170 @@
+# Portfolio Assistant Demo - Chart Additions Plan
+
+## Overview
+
+This document outlines the planned additions of charts to the Portfolio Assistant demo to make it more visually compelling and useful. These additions will be implemented after the necessary DTOs and chart type support are added to the codebase.
+
+## Planned Chart Additions
+
+### 1. Line Chart - Portfolio Performance Over Time
+
+**Location:** After portfolio strategy description, before "Current Portfolio Exposures" section
+
+**Purpose:** 
+- Provide historical context for the portfolio
+- Show performance trends over time
+- Help users understand why rebalancing might be needed
+
+**Data to Display:**
+- X-axis: Time periods (e.g., monthly or quarterly over 1-3 years)
+- Y-axis: Portfolio value or cumulative return (%)
+- Series: Portfolio performance, optionally with benchmark comparison
+
+**Example Flow:**
+```
+Portfolio Strategy Description
+  ↓
+[Line Chart: Portfolio Performance Over Time] ← NEW
+  ↓
+Current Portfolio Exposures (table)
+```
+
+**Implementation Requirements:**
+- Add `line_chart` block type support
+- Create `LineChartData` DTO with:
+  - `x_categories`: list of time periods
+  - `y_values`: list of series (each series is a list of values)
+  - `x_label`: string (e.g., "Time")
+  - `y_label`: string (e.g., "Portfolio Value")
+  - Optional: `series_labels` for multiple series
+
+---
+
+### 2. Slider-Adjustable Side-by-Side Bar Chart - Risk/Allocation Relationship
+
+**Location:** During risk adjustment flow, after the risk slider is displayed
+
+**Purpose:**
+- Visualize how portfolio allocation changes with different risk levels
+- Show current allocation vs. target allocation at selected risk level
+- Provide real-time feedback as user adjusts risk slider
+
+**Data to Display:**
+- X-axis: Asset classes/sectors (Bonds, Equities, Cash, etc.)
+- Two series: 
+  - "Current Allocation" (static)
+  - "Target at Risk X" (updates based on slider value)
+- Y-axis: Allocation percentage (0-100%)
+
+**Example Flow:**
+```
+Risk Adjustment Prompt
+  ↓
+[Risk Slider: 1-10] ← Existing
+  ↓
+[Side-by-Side Bar Chart: Current vs Target Allocation] ← NEW (updates with slider)
+  ↓
+"Updating risk level..." action
+```
+
+**Implementation Requirements:**
+- Extend `BarChartData` DTO to support:
+  - Slider binding/relationship
+  - Dynamic updates based on external state (slider value)
+  - Mechanism to link chart data to slider value
+  
+**Design Considerations:**
+- How should the chart receive slider updates? (event-driven, reactive, etc.)
+- Should the chart be a single block that updates, or multiple blocks?
+- How do we structure the data to support multiple risk levels?
+  - Option A: Pre-compute all risk levels, chart selects based on slider
+  - Option B: Chart receives slider value and computes target allocation
+  - Option C: Chart is updated via separate events as slider changes
+
+**Proposed Data Structure:**
+```json
+{
+  "block_type": "bar_chart",
+  "data": {
+    "x_categories": ["Bonds", "Equities", "Cash"],
+    "y_values": [
+      [30, 65, 5],   // Current allocation (static)
+      [30, 65, 5]    // Target allocation (updates with slider)
+    ],
+    "colour_categories": ["Current", "Target at Risk 7"],
+    "x_label": "Asset Class",
+    "y_label": "Allocation %",
+    "slider_binding": {
+      "slider_block_id": "risk-level",
+      "value_mapping": {
+        "1": [[60, 30, 10]],
+        "2": [[55, 35, 10]],
+        // ... mappings for each risk level
+        "10": [[10, 85, 5]]
+      }
+    }
+  }
+}
+```
+
+---
+
+## Implementation Order
+
+### Phase 1: Line Chart Support
+1. Add `line_chart` to block type Literal in `Event` model
+2. Create `LineChartData` DTO in `block_data.py`
+3. Implement `line_chart` block factory in `blocks/line_chart.py`
+4. Add tests in `test_blocks.py`
+5. Add line chart to demo JSON
+
+### Phase 2: Slider-Adjustable Bar Chart Support
+1. Design DTO structure for slider-binding (see considerations above)
+2. Extend `BarChartData` or create new variant
+3. Implement update mechanism (event-driven vs reactive)
+4. Add tests for slider-bound charts
+5. Add slider-adjustable bar chart to demo JSON
+
+### Phase 3: Demo Integration
+1. Add line chart after portfolio strategy descriptions (all three portfolio flows)
+2. Add slider-adjustable bar chart in risk adjustment flows (all three risk adjustment branches)
+3. Ensure chart data aligns with existing table data for consistency
+4. Test full demo flow
+
+---
+
+## Data Consistency Notes
+
+- Line chart data should be consistent with portfolio performance mentioned in strategy descriptions
+- Bar chart allocation data should align with:
+  - Current exposures tables
+  - Rebalancing strategy tables
+  - Risk level descriptions (e.g., Risk 7 = Moderate-High)
+
+---
+
+## Open Questions
+
+1. **Line Chart:**
+   - Should we show multiple series (portfolio vs benchmark)?
+   - What time period is most useful? (1Y, 3Y, 5Y?)
+   - Should we show absolute values or percentage returns?
+
+2. **Slider-Adjustable Bar Chart:**
+   - Should updates be immediate (as slider moves) or on slider release?
+   - How do we handle the initial state before slider interaction?
+   - Should we show a third series for "Change" (target - current)?
+
+3. **General:**
+   - Should charts replace tables or complement them?
+   - Do we need chart titles/captions in the DTOs?
+
+---
+
+## References
+
+- Current demo: `portfolio_assistant_stream.json`
+- Bar chart implementation: `src/yera/chat/blocks/bar_chart.py`
+- Block data models: `src/yera/chat/models/block_data.py`
+- Event model: `src/yera/chat/models/event.py`
+