AIappsGBBFactory
diff --git a/‎.gitattributes‎
Lines changed: 3 additions & 0 deletions b/‎.gitattributes‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎.github/copilot-instructions.md‎
Lines changed: 39 additions & 83 deletions b/‎.github/copilot-instructions.md‎
Lines changed: 39 additions & 83 deletions
diff --git a/‎.github/instructions/api-endpoints.instructions.md‎
Lines changed: 49 additions & 0 deletions b/‎.github/instructions/api-endpoints.instructions.md‎
Lines changed: 49 additions & 0 deletions
diff --git a/‎.github/instructions/python.instructions.md‎
Lines changed: 46 additions & 0 deletions b/‎.github/instructions/python.instructions.md‎
Lines changed: 46 additions & 0 deletions
diff --git a/‎.github/skills/README.md‎
Lines changed: 42 additions & 0 deletions b/‎.github/skills/README.md‎
Lines changed: 42 additions & 0 deletions
@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads
@@ -1,83 +1,39 @@
-Developer: # 🦠 Copilot Developer Guide for Real-Time Voice Apps (Python 3.11, FastAPI, Azure)
-
----
-
-## 🚀 Overview
-Develop Python 3.11 code for a **low-latency, real-time voice application** utilizing the following technologies:
-
-- **FastAPI**
-- **Azure Communication Services** (Call Automation & Media Streaming)
-- **Azure Speech** (Speech-to-Text/Text-to-Speech)
-- **Azure OpenAI**
-
-Begin every significant task by outlining a concise checklist (3–7 bullets) of conceptual steps before proceeding; keep these at a high level. Focus on clarity, manageable increments, and code simplicity. Avoid unnecessary abstraction or complexity. Prioritize practical, focused updates over clever or intricate changes.
-
----
-
-## 📄 General Principles
-- **Readability & Simplicity:** Write clear, maintainable code that is easy to understand.
-- **Simplicity First:** Choose the simplest working solution. Avoid over-engineering and premature optimization.
-- **Incremental Development:** Implement small, meaningful changes rather than large, complex modifications.
-- **Modular Design:** Separate infrastructure, backend logic, and user experience layers.
-- **Asynchronous Endpoints:** Define all HTTP and WebSocket handlers as `async` functions.
-- **Schemas:** Use `pydantic.BaseModel` for all request and response definitions.
-- **Dependency Injection:** Use FastAPI `Depends` for managing sessions, authentication, and Redis clients.
-- **Configuration Management:** Store secrets and configuration in environment variables or a `.env` file.
-- **Structured Logging:** Output logs in JSON format, including `correlation ID`, `callConnectionId`, etc.
-- **Avoid Blocking I/O:** Do not use global state; manage resource lifecycles in scoped containers.
-
----
-
-## 🔎 Tracing & Application Instrumentation
-- **OpenTelemetry:** Instrument all code using OpenTelemetry (OTEL). Set `service.name` and `service.instance.id` on the `TracerProvider` resource.
-- **Span Kinds:** Use `SERVER` for inbound HTTP/WS handlers, `CLIENT` for outbound requests, and `INTERNAL` for local processing activities.
-- **Context Propagation:** Employ the W3C `traceparent` header for HTTP/WS and span links for inter-process activities.
-- **Root Traces:** Create one per `callConnectionId`, including `rt.call.connection_id` and `rt.session.id` as attributes.
-- **Span Volume:** Limit span creation; generate one session span for STT (with events) and, optionally, one per VAD segment. **Do not create spans per audio frame.**
-- **Semantic Attributes:** Apply attributes like `peer.service`, `net.peer.name`, `http.request.method`, `server.address`, and `network.protocol.name="websocket"`.
-- **Error Reporting:** If errors occur, set span status to `ERROR` and attach an event with `error.type` and `error.message`.
-
-After each tool invocation or code edit, validate the result in 1–2 lines. If the output does not meet expectations, self-correct and retry as needed before proceeding.
-
----
-
-## 🏗️ App Structure & Dependency Management
-- **No Client Attachment:** Refrain from storing clients on `Request` or `WebSocket` objects.
-- **Typed AppContainer:** Define protocols for Redis, Speech, and Azure OpenAI; attach these to `app.state` and provide access via FastAPI dependencies.
-- **WebSocket Dependency Injection:** Inject dependencies with `container_from_ws(ws)`; do not access `ws.app.state.*` directly.
-
----
-
-## 📞 Azure Communication Services (ACS) Best Practices
-- **Call Connection ID:** Treat `callConnectionId` as a correlation token, not a secret; prefer passing via headers or message bodies.
-- **Spans for Media Operations:** Use `SERVER` spans for WebSocket accept operations, `CLIENT` spans for ACS control commands (answer, play, stop, hangup).
-
----
-
-## ✨ Code Style Guide
-- **Small, Focused Functions:** Use explicit timeouts on `await` statements; avoid blocking event loops. Make code changes as minimal, reviewable increments.
-- **Favor Clarity:** Regularly review solutions to eliminate unnecessary complexity. Avoid deep inheritance, extra abstraction, or unused patterns.
-- **Background Tasks:** Use `asyncio.create_task` and manage background task lifecycles appropriately.
-- **Docstrings:** Always include descriptions of function inputs, outputs, and latency concerns.
-- **Unit Testing:** Support testability by faking/mocking Redis, Speech, and AOAI via Protocols. Ensure your code can be unit tested.
-
-When editing code:
-1. Clearly state your assumptions.
-2. Create or run minimal, relevant tests when possible.
-3. Produce reviewable diffs and adhere to project standards.
-If tests cannot be run, note that they are speculative and provide instructions for local validation.
-
-After code changes, always verify the edits against expected behavior and prepare to self-correct if validation fails.
-
----
-
-## 🚫 Strictly Prohibited
-- Creating spans per audio chunk.
-- Using global singletons.
-- Adding `service.name` or `span.kind` attributes to spans manually.
-
----
-
-> **Tip:** Use code blocks, lists, and semantic section headers to maximize clarity and increase inferencing accuracy. Default to plain text unless markdown is requested; use code fences for code and backticks for identifiers.
-
----
+# Copilot Guide: Real-Time Voice Apps (Python 3.11, FastAPI, Azure)
+
+## Stack
+- **FastAPI** + **Pydantic** for APIs
+- **Azure Communication Services** (Call Automation, Media Streaming)
+- **Azure Speech** (TTS/STT), **Azure OpenAI**
+- **Redis** for session state, **Cosmos DB** for persistence
+
+## Core Principles
+- **Simplicity First:** Choose the simplest working solution. No over-engineering.
+- **Reuse Before Create:** Check `src/`, `utils/`, `config/` before writing new code.
+- **Async Everything:** All HTTP/WebSocket handlers must be `async`.
+- **No Wrappers:** Do not create adapter/facade/manager classes around existing services.
+- **No New Dependencies:** Do not add pip packages without explicit approval.
+
+## Key Modules to Reuse
+| Need | Use |
+|------|-----|
+| Logging | `from utils.ml_logging import get_logger` |
+| Configuration | `from config.settings import X` (not `os.getenv`) |
+| Redis | `src/redis/manager.py` |
+| Azure OpenAI | `src/aoai/` |
+| Speech TTS/STT | `src/speech/` |
+| Agents | `registries/agentstore/base.py` → `UnifiedAgent` |
+| Tools | `registries/toolstore/` |
+| Pydantic models | Extend `api/v1/models/base.py` → `BaseModel` |
+
+## Anti-Patterns (Never Do)
+- Global singletons or module-level mutable state
+- Factory classes when a function suffices
+- Abstract base classes for single implementations
+- `logging.getLogger()` — use `get_logger(__name__)`
+- `os.getenv()` — import from `config/settings.py`
+- `requests` library — use `aiohttp` or `httpx`
+
+## Telemetry
+- Use OpenTelemetry with W3C `traceparent` propagation
+- One trace per `callConnectionId`, not per audio frame
+- Span kinds: `SERVER` (inbound), `CLIENT` (outbound), `INTERNAL` (local)
@@ -0,0 +1,49 @@
+---
+applyTo: "**/api/**/*.py,**/endpoints/**/*.py,**/handlers/**/*.py"
+---
+
+# API Endpoint Standards
+
+## Router Setup
+```python
+from fastapi import APIRouter, Request, HTTPException, Depends
+from utils.ml_logging import get_logger
+
+router = APIRouter()
+logger = get_logger(__name__)
+```
+
+## Endpoint Pattern
+```python
+@router.get("/path", response_model=ResponseSchema, tags=["Category"])
+async def endpoint_name(request: Request) -> ResponseSchema:
+    """Brief description of what this endpoint does."""
+    # Access shared resources via request.app.state
+    # Return Pydantic model, not dict
+```
+
+## Request/Response
+- Use Pydantic schemas from `api/v1/schemas/` for all request/response models
+- Extend `BaseModel` from `api/v1/models/base.py` for new models
+- Never return raw dicts — always use response_model
+
+## Dependency Injection
+- Use `Depends()` for auth, sessions, clients
+- Access app state: `request.app.state.redis_client`
+- WebSocket: use `container_from_ws(ws)`, not direct state access
+
+## Error Responses
+```python
+# Standard error format
+raise HTTPException(status_code=404, detail="Resource not found")
+
+# With logging
+logger.error(f"Failed to fetch resource {id}: {e}")
+raise HTTPException(status_code=500, detail=str(e))
+```
+
+## Tags for OpenAPI
+- `Health` — health/readiness endpoints
+- `Calls` — call management
+- `Agents` — agent operations
+- `Voice` — voice/speech operations
@@ -0,0 +1,46 @@
+---
+applyTo: "**/*.py"
+---
+
+# Python Code Standards
+
+## Imports & Setup
+```python
+from __future__ import annotations
+from utils.ml_logging import get_logger
+
+logger = get_logger(__name__)
+```
+
+## Type Hints
+- Full type hints on all functions and methods
+- Use `X | None` instead of `Optional[X]`
+- Use `TypeVar` for generic classes
+
+## Async Patterns
+- All I/O operations must be `async`
+- Use explicit timeouts: `await asyncio.wait_for(coro, timeout=5.0)`
+- Background tasks: `asyncio.create_task()` with proper lifecycle management
+- Never use blocking `requests` — use `aiohttp` or `httpx`
+
+## Error Handling
+- Use `HTTPException` for API errors with appropriate status codes
+- Always log errors before raising: `logger.error(f"...: {e}")`
+- Use `tenacity` for retries (already in deps), not custom retry logic
+
+## Functions Over Classes
+```python
+# ✅ Prefer
+async def process_item(item: Item) -> Result:
+    return Result(data=item.transform())
+
+# ❌ Avoid unnecessary abstraction
+class ItemProcessor:
+    async def process(self, item: Item) -> Result:
+        return Result(data=item.transform())
+```
+
+## Docstrings
+- Include for public functions
+- Describe inputs, outputs, and any latency concerns
+- Keep concise — one-liner if behavior is obvious
@@ -0,0 +1,42 @@
+# Skills Directory
+
+Task-oriented skills for AI assistants working with this codebase.
+
+## Philosophy
+
+**Code is documentation.** Skills provide focused task guidance; the codebase itself is the reference. Agents should explore existing patterns via:
+
+- `registries/toolstore/registry.py` - Tool registration patterns
+- `registries/agentstore/base.py` - Agent schema and helpers
+- `registries/agentstore/*/agent.yaml` - Agent configuration examples
+
+## Available Skills
+
+| Skill | Description |
+| ----- | ----------- |
+| `add-component` | Add React component with Material UI |
+| `add-endpoint` | Add FastAPI endpoint |
+| `add-evaluation` | Create evaluation scenario |
+| `add-message-handler` | Handle new WebSocket message type |
+| `add-tool` | Add tool to agent registry |
+| `add-voice-handler` | Add voice module feature |
+| `create-agent` | Create complete agent with tools |
+
+## Skill Conventions
+
+Each skill lives in `.github/skills/{skill-name}/SKILL.md` with frontmatter:
+
+```yaml
+---
+name: skill-name
+description: Brief task description
+---
+```
+
+**Supported attributes:** `name`, `description`, `compatibility`, `license`, `metadata`
+
+## Naming
+
+- `add-*` for creating new items (add-endpoint, add-tool)
+- `create-*` for complex multi-file creation (create-agent)
+- Verb-noun pattern, lowercase, hyphenated
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+`
	`2`	`+# Use bd merge for beads JSONL files`
	`3`	`+.beads/issues.jsonl merge=beads`