vs-agent 0.1.1__py3-none-any.whl

vs_agent/__init__.py

@@ -0,0 +1,5 @@
+from vs_agent.server.vs_agent_server import VsAgentServer
+
+__all__ = [
+    "VsAgentServer",
+]

vs_agent/auth/vs_action_security.py

@@ -0,0 +1,16 @@
+from typing import List, Optional
+
+from vs_security.guard.vs_security import get_auth_context
+
+
+class VsActionSecurity:
+
+    def __init__(self, roles: Optional[List[str]] = None):
+        self._roles = roles or []
+
+    async def __call__(self) -> None:
+        ctx = get_auth_context()
+        if ctx is None:
+            raise PermissionError("Unauthenticated request")
+        if self._roles and not ctx.has_any_role(*self._roles):
+            raise PermissionError(f"Required roles: {self._roles}")

vs_agent/client/vs_peer_agent_client.py

@@ -0,0 +1,72 @@
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, Optional
+
+import httpx
+import jwt
+
+from vs_agent.discovery.vs_peer_agent_registry import VsPeerAgentRegistry
+from vs_common.config.vs_base_config import VsBaseConfig
+from vs_common.log.vs_log_manager import VsLogManager
+
+_SERVICE_ID = str(uuid.uuid5(uuid.NAMESPACE_DNS, "vs-agent-peer-client"))
+_logger = VsLogManager.get_instance("VsPeerAgentClient")
+
+
+class VsPeerAgentClient:
+
+    _secret: Optional[str] = None
+    _algorithm: str = "HS256"
+    _expiry_minutes: int = 2
+
+    @classmethod
+    def init(cls, config: VsBaseConfig) -> None:
+        cls._secret = config.get("agent_client.secret_key", default=None)
+        cls._algorithm = config.get("agent_client.algorithm", default="HS256")
+        cls._expiry_minutes = config.get("agent_client.access_expiry_minutes", default=2, data_type=int)
+
+    @classmethod
+    def _mint_token(cls) -> Optional[str]:
+        if not cls._secret:
+            return None
+        now = datetime.now(timezone.utc)
+        payload = {
+            "sub": _SERVICE_ID,
+            "username": "vs-agent",
+            "roles": ["service"],
+            "provider": "internal",
+            "type": "access",
+            "iat": now,
+            "exp": now + timedelta(minutes=cls._expiry_minutes),
+        }
+        return jwt.encode(payload, cls._secret, algorithm=cls._algorithm)
+
+    @classmethod
+    def _headers(cls) -> Dict[str, str]:
+        token = cls._mint_token()
+        return {"Authorization": f"Bearer {token}"} if token else {}
+
+    @classmethod
+    async def call(
+        cls,
+        agent: str,
+        path: str,
+        payload: Dict[str, Any],
+        method: str = "POST",
+        timeout: float = 230.0,
+    ) -> dict:
+        entry = VsPeerAgentRegistry.get(agent)
+        if entry is None:
+            raise ValueError(f"Agent '{agent}' is not registered.")
+        if entry.status == "offline":
+            raise RuntimeError(f"Agent '{agent}' is currently offline.")
+
+        url = f"{entry.url}{path}"
+        _logger.info(f"Calling peer agent '{agent}' → {method} {url}")
+
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            response = await getattr(client, method.lower())(
+                url, json=payload, headers=cls._headers()
+            )
+            response.raise_for_status()
+            return response.json()

vs_agent/decorator/vs_action_decorator.py

@@ -0,0 +1,23 @@
+from typing import Any, Callable, Dict, List, Optional
+
+from vs_agent.registry.vs_action_registry import VsActionRegistry
+from vs_agent.schema.vs_action_schema import Intent
+from vs_mcp_agent.registry.vs_tool_registry import VsToolRegistry
+
+
+def action(
+    name: str,
+    description: str,
+    path: str,
+    method: str = "POST",
+    intents: Optional[List[Intent]] = None,
+    input_schema: Optional[Dict[str, Any]] = None,
+    guards: Optional[List[Callable]] = None,
+):
+    def decorator(fn: Callable) -> Callable:
+        _guards = guards or []
+        _intents = intents or []
+        VsToolRegistry.register_fn(name, description, fn, guards=_guards)
+        VsActionRegistry.register(name, description, path, method, _intents, input_schema, _guards, fn)
+        return fn
+    return decorator

vs_agent/discovery/vs_peer_agent_registry.py

@@ -0,0 +1,73 @@
+import threading
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+
+@dataclass
+class PeerAgentEntry:
+    name: str
+    url: str
+    status: str = "offline"
+    version: Optional[str] = None
+    capabilities: list = field(default_factory=list)
+    last_health_check: Optional[datetime] = None
+
+
+_RESERVED_KEYS = {"health_check_interval"}
+
+
+class VsPeerAgentRegistry:
+
+    _entries: Dict[str, PeerAgentEntry] = {}
+    _lock = threading.Lock()
+
+    @classmethod
+    def register(cls, name: str, url: str) -> None:
+        with cls._lock:
+            if name not in cls._entries:
+                cls._entries[name] = PeerAgentEntry(name=name, url=url)
+
+    @classmethod
+    def set_online(cls, name: str, version: Optional[str], capabilities: list) -> None:
+        with cls._lock:
+            if name in cls._entries:
+                entry = cls._entries[name]
+                entry.status = "online"
+                entry.version = version
+                entry.capabilities = capabilities
+                entry.last_health_check = datetime.now(timezone.utc)
+
+    @classmethod
+    def set_version_unchanged(cls, name: str) -> None:
+        with cls._lock:
+            if name in cls._entries:
+                entry = cls._entries[name]
+                entry.status = "online"
+                entry.last_health_check = datetime.now(timezone.utc)
+
+    @classmethod
+    def set_offline(cls, name: str) -> None:
+        with cls._lock:
+            if name in cls._entries:
+                entry = cls._entries[name]
+                entry.status = "offline"
+                entry.last_health_check = datetime.now(timezone.utc)
+
+    @classmethod
+    def get(cls, name: str) -> Optional[PeerAgentEntry]:
+        return cls._entries.get(name)
+
+    @classmethod
+    def get_available(cls) -> List[PeerAgentEntry]:
+        with cls._lock:
+            return [e for e in cls._entries.values() if e.status == "online"]
+
+    @classmethod
+    def get_all(cls) -> List[PeerAgentEntry]:
+        with cls._lock:
+            return list(cls._entries.values())
+
+    @classmethod
+    def parse_agents_config(cls, section: Dict[str, str]) -> Dict[str, str]:
+        return {k: v for k, v in section.items() if k not in _RESERVED_KEYS}

vs_agent/discovery/vs_peer_agent_scheduler.py

@@ -0,0 +1,34 @@
+import asyncio
+from typing import Optional
+
+from vs_common.log.vs_log_manager import VsLogManager
+
+
+class VsPeerAgentScheduler:
+
+    def __init__(self, health_interval: int = 30):
+        self._health_interval = health_interval
+        self._task: Optional[asyncio.Task] = None
+        self._logger = VsLogManager.get_instance(self.__class__.__name__)
+
+    async def start(self) -> None:
+        self._task = asyncio.create_task(self._health_loop())
+        self._logger.info(f"Peer agent scheduler started (interval={self._health_interval}s)")
+
+    async def stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        self._logger.info("Peer agent scheduler stopped")
+
+    async def _health_loop(self) -> None:
+        from vs_agent.discovery.vs_peer_capability_loader import VsPeerCapabilityLoader
+        while True:
+            await asyncio.sleep(self._health_interval)
+            try:
+                await VsPeerCapabilityLoader.check_all()
+            except Exception as e:
+                self._logger.error(f"Health check cycle failed: {e}", exc_info=True)

vs_agent/discovery/vs_peer_capability_loader.py

@@ -0,0 +1,81 @@
+from typing import Dict
+
+import httpx
+
+from vs_agent.discovery.vs_peer_agent_registry import VsPeerAgentRegistry
+from vs_common.log.vs_log_manager import VsLogManager
+
+_logger = VsLogManager.get_instance("VsPeerCapabilityLoader")
+
+
+class VsPeerCapabilityLoader:
+
+    @classmethod
+    async def load_all(cls, agents: Dict[str, str]) -> None:
+        _logger.info(f"Loading peer agents: {list(agents.keys())}")
+        for name, url in agents.items():
+            VsPeerAgentRegistry.register(name, url)
+            _logger.debug(f"[{name}] registered at {url}")
+        for name, url in agents.items():
+            await cls._check(name, url)
+        cls._log_summary()
+
+    @classmethod
+    async def check_all(cls) -> None:
+        _logger.debug("Running peer agent health check cycle")
+        for entry in VsPeerAgentRegistry.get_all():
+            await cls._check(entry.name, entry.url)
+        cls._log_summary()
+
+    @classmethod
+    async def _check(cls, name: str, url: str) -> None:
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                resp = await client.get(f"{url}/health")
+                resp.raise_for_status()
+                health = resp.json()
+
+            new_version = health.get("version")
+            entry = VsPeerAgentRegistry.get(name)
+            was_offline = entry and entry.status == "offline"
+
+            needs_capabilities = (
+                entry is None
+                or was_offline
+                or entry.version != new_version
+                or not entry.capabilities
+            )
+
+            if needs_capabilities:
+                reason = "came online" if was_offline else f"version changed {entry.version} → {new_version}" if entry and entry.version != new_version else "initial load"
+                _logger.info(f"[{name}] fetching capabilities ({reason})")
+                capabilities = await cls._fetch_capabilities(url)
+                VsPeerAgentRegistry.set_online(name, new_version, capabilities)
+                action_names = [a.get("name") for a in capabilities]
+                _logger.info(f"[{name}] online  version={new_version}  actions={action_names}")
+            else:
+                VsPeerAgentRegistry.set_version_unchanged(name)
+                _logger.debug(f"[{name}] online  version={new_version}  (no changes)")
+
+        except Exception as e:
+            entry = VsPeerAgentRegistry.get(name)
+            was_online = entry and entry.status == "online"
+            VsPeerAgentRegistry.set_offline(name)
+            if was_online:
+                _logger.warning(f"[{name}] went offline: {e}")
+            else:
+                _logger.debug(f"[{name}] still offline: {e}")
+
+    @classmethod
+    async def _fetch_capabilities(cls, url: str) -> list:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            resp = await client.get(f"{url}/capabilities")
+            resp.raise_for_status()
+            return resp.json().get("actions", [])
+
+    @classmethod
+    def _log_summary(cls) -> None:
+        all_entries = VsPeerAgentRegistry.get_all()
+        online = [e.name for e in all_entries if e.status == "online"]
+        offline = [e.name for e in all_entries if e.status == "offline"]
+        _logger.info(f"Peer agents — online: {online}  offline: {offline}")

vs_agent/registry/vs_action_registry.py

@@ -0,0 +1,51 @@
+import threading
+from typing import Any, Callable, Dict, List, NamedTuple, Optional
+
+from vs_agent.schema.vs_action_schema import Intent
+
+
+class _ActionEntry(NamedTuple):
+    name: str
+    description: str
+    path: str
+    method: str
+    intents: List[Intent]
+    input_schema: Optional[Dict[str, Any]]
+    guards: List[Callable]
+    fn: Callable
+
+
+class VsActionRegistry:
+    _registry: Dict[str, _ActionEntry] = {}
+    _lock: threading.Lock = threading.Lock()
+
+    @classmethod
+    def register(
+        cls,
+        name: str,
+        description: str,
+        path: str,
+        method: str,
+        intents: List[Intent],
+        input_schema: Optional[Dict[str, Any]],
+        guards: List[Callable],
+        fn: Callable,
+    ) -> None:
+        with cls._lock:
+            if name in cls._registry:
+                raise ValueError(f"Action '{name}' is already registered")
+            cls._registry[name] = _ActionEntry(
+                name=name,
+                description=description,
+                path=path,
+                method=method,
+                intents=intents,
+                input_schema=input_schema,
+                guards=guards,
+                fn=fn,
+            )
+
+    @classmethod
+    def get_all(cls) -> Dict[str, _ActionEntry]:
+        with cls._lock:
+            return dict(cls._registry)

vs_agent/schema/vs_action_schema.py

@@ -0,0 +1,21 @@
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel
+
+
+class Intent(BaseModel):
+    name: str
+    description: str
+    examples: Optional[List[str]] = None
+
+
+class ActionCapability(BaseModel):
+    name: str
+    description: str
+    path: str
+    method: str
+    intents: List[Intent]
+    input_schema: Optional[Dict[str, Any]] = None
+
+
+class CapabilitiesResponse(BaseModel):
+    actions: List[ActionCapability]

vs_agent/server/vs_agent_server.py

@@ -0,0 +1,182 @@
+import functools
+import inspect
+import threading
+from typing import Optional
+
+from vs_agent.registry.vs_action_registry import VsActionRegistry
+from vs_common.config.vs_base_config import VsBaseConfig
+from vs_common.log.vs_log_manager import VsLogManager
+from vs_server.server.vs_server import VsServer
+
+
+class VsAgentServer:
+
+    def __init__(
+        self,
+        config: VsBaseConfig,
+        http: Optional[str] = "fastapi",
+        mcp: Optional[str] = None,
+    ):
+        if not http and not mcp:
+            raise ValueError("At least one of 'http' or 'mcp' must be specified.")
+
+        self._config = config
+        self._logger = VsLogManager.get_instance(self.__class__.__name__)
+        self._http_server: Optional[VsServer] = None
+        self._mcp_server = None
+
+        if http:
+            from vs_server.factory.vs_server_factory import VsServerFactory
+            self._http_server = VsServerFactory.get(http, config)
+
+        if mcp:
+            from vs_mcp_agent.factory.vs_mcp_server_factory import VsMcpServerFactory
+            self._mcp_server = VsMcpServerFactory.get(mcp, config)
+
+        self._setup_peer_discovery(config)
+
+    # --- HTTP delegation ---
+
+    def add_controller(self, controller) -> "VsAgentServer":
+        self._require_http().add_controller(controller)
+        return self
+
+    def add_router(self, router) -> "VsAgentServer":
+        self._require_http().add_router(router)
+        return self
+
+    def add_websocket(self, handler) -> "VsAgentServer":
+        self._require_http().add_websocket(handler)
+        return self
+
+    def add_sse(self, handler) -> "VsAgentServer":
+        self._require_http().add_sse(handler)
+        return self
+
+    def get_app(self):
+        return self._require_http().get_app()
+
+    # --- MCP accessor ---
+
+    @property
+    def mcp(self):
+        if self._mcp_server is None:
+            raise RuntimeError("No MCP server configured. Pass mcp='fastmcp' to VsAgentServer.")
+        return self._mcp_server.mcp
+
+    # --- Actions (HTTP + MCP dual-registration) ---
+
+    def add_actions(self) -> "VsAgentServer":
+        from vs_agent.registry.vs_action_registry import VsActionRegistry
+
+        entries = VsActionRegistry.get_all()
+        if not entries:
+            return self
+
+        if self._http_server is not None:
+            self._register_http_actions(entries)
+
+        return self
+
+    def _register_http_actions(self, entries: dict) -> None:
+        from fastapi import APIRouter, Depends
+        from vs_agent.schema.vs_action_schema import ActionCapability, CapabilitiesResponse
+
+        security_deps = []
+        auth_enabled = self._config.get("agent.auth_enabled", default=True, data_type=bool)
+        if auth_enabled:
+            try:
+                from fastapi.security import HTTPBearer
+                from vs_security.guard.vs_security import VsSecurity
+                security_deps = [Depends(VsSecurity.from_manager()), Depends(HTTPBearer())]
+            except Exception:
+                pass
+
+        router = APIRouter()
+
+        @router.get("/capabilities")
+        async def capabilities() -> CapabilitiesResponse:
+            return CapabilitiesResponse(actions=[
+                ActionCapability(
+                    name=e.name,
+                    description=e.description,
+                    path=e.path,
+                    method=e.method,
+                    intents=e.intents,
+                    input_schema=e.input_schema,
+                )
+                for e in VsActionRegistry.get_all().values()
+            ])
+
+        for entry in entries.values():
+            fn = entry.fn
+            if entry.guards:
+                @functools.wraps(fn)
+                async def _handler(*args, _fn=fn, _guards=entry.guards, **kwargs):
+                    for guard in _guards:
+                        await guard()
+                    return await _fn(*args, **kwargs)
+                _handler.__signature__ = inspect.signature(fn)
+                handler = _handler
+            else:
+                handler = fn
+
+            guard_deps = [Depends(g) for g in entry.guards]
+            getattr(router, entry.method.lower())(
+                entry.path,
+                dependencies=security_deps + guard_deps,
+            )(handler)
+
+        base_url = self._config.get("server.base_url", default="")
+        self._http_server.add_router(router, prefix=base_url)
+
+    # --- Run ---
+
+    def run(self) -> None:
+        if self._http_server and self._mcp_server:
+            mcp_thread = threading.Thread(target=self._mcp_server.run, daemon=True)
+            mcp_thread.start()
+            self._logger.info(f"[MCP]  listening on port {self._mcp_server._config.port}")
+            self._logger.info(f"[HTTP] listening on port {self._config.get('server.port', 8000, int)}")
+            self._http_server.run()
+        elif self._mcp_server:
+            self._mcp_server.run()
+        else:
+            self._http_server.run()
+
+    # --- Peer discovery ---
+
+    def _setup_peer_discovery(self, config: VsBaseConfig) -> None:
+        agents_section = config.get_section("agents")
+        if not agents_section:
+            return
+
+        from vs_agent.discovery.vs_peer_agent_registry import VsPeerAgentRegistry
+        from vs_agent.discovery.vs_peer_capability_loader import VsPeerCapabilityLoader
+        from vs_agent.discovery.vs_peer_agent_scheduler import VsPeerAgentScheduler
+        from vs_agent.client.vs_peer_agent_client import VsPeerAgentClient
+        from vs_server.lifecycle.vs_lifecycle import startup, shutdown
+
+        agents = VsPeerAgentRegistry.parse_agents_config(agents_section)
+        health_interval = int(agents_section.get("health_check_interval", 30))
+
+        scheduler = VsPeerAgentScheduler(health_interval=health_interval)
+        VsPeerAgentClient.init(config)
+
+        @startup
+        async def _peer_discovery_start():
+            await VsPeerCapabilityLoader.load_all(agents)
+            await scheduler.start()
+
+        @shutdown
+        async def _peer_discovery_stop():
+            await scheduler.stop()
+
+        self._logger.info(f"Peer discovery enabled for agents: {list(agents.keys())}")
+
+    # --- Internal ---
+
+    def _require_http(self) -> VsServer:
+        if self._http_server is None:
+            raise RuntimeError("No HTTP server configured. Pass http='fastapi' to VsAgentServer.")
+        return self._http_server

vs_agent-0.1.1.dist-info/METADATA

@@ -0,0 +1,692 @@
+Metadata-Version: 2.4
+Name: vs-agent
+Version: 0.1.1
+Summary: Full-stack agent framework for Viveka Sutra — HTTP + MCP server in one
+Project-URL: Homepage, https://vivekasutra.com/
+Project-URL: Source, https://github.com/vivekasutra/viveka-mula
+Keywords: agent,mcp,fastapi,http,viveka,vs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: vs-common
+Requires-Dist: vs-server
+Provides-Extra: mcp
+Requires-Dist: vs-mcp-agent; extra == "mcp"
+Provides-Extra: security
+Requires-Dist: vs-security; extra == "security"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# vs-agent
+
+Full-stack agent framework for Viveka Sutra — build agents that serve over HTTP, MCP, or both, from a single codebase.
+
+---
+
+## Overview
+
+`vs-agent` combines `vs-server` (HTTP/WebSocket/SSE) and `vs-mcp-agent` (MCP) into a single `VsAgentServer`. It lets you expose a capability once with `@action` and have it available simultaneously as an HTTP endpoint and an MCP tool — with the same auth, guards, and business logic.
+
+The library is fully server-agnostic. `VsAgentServer` does not hardcode FastAPI or FastMCP — it uses `VsServerFactory` and `VsMcpServerFactory` to resolve the correct server implementation at startup. Swapping or adding a new server type requires no changes to application code.
+
+---
+
+## The Problem It Solves
+
+An agent needs to be callable by both humans (via HTTP) and AI clients (via MCP). Without `vs-agent`, you register the same function twice, apply guards twice, and maintain two sets of route definitions.
+
+### Without vs-agent
+
+```python
+# HTTP route
+@router.post("/v1/docs/search")
+async def search_docs_http(query: str, auth=Depends(require_auth)):
+    return await _search(query)
+
+# MCP tool — separate registration, separate guard wiring
+@mcp.tool(name="search_docs")
+async def search_docs_mcp(query: str) -> dict:
+    await require_auth()
+    return await _search(query)
+```
+
+### With vs-agent
+
+```python
+@action(
+    name="search_docs",
+    description="Search VS library documentation",
+    path="/v1/docs/search",
+    guards=[VsActionSecurity(roles=["user"])],
+)
+async def search_docs(query: str) -> VsToolResponse:
+    return VsToolResponse(status="success", result=await _search(query))
+```
+
+One function, one guard, available on both protocols.
+
+---
+
+## Installation
+
+```bash
+pip install vs-agent
+```
+
+With MCP support:
+
+```bash
+pip install vs-agent[mcp]
+```
+
+With auth guard support:
+
+```bash
+pip install vs-agent[mcp,security]
+```
+
+---
+
+## Dependencies
+
+| Library | Required | Purpose |
+|---|---|---|
+| `vs-common` | Yes | Config, logging |
+| `vs-server` | Yes | HTTP/WebSocket/SSE server |
+| `vs-mcp-agent` | No — install with `[mcp]` extra | MCP server |
+| `vs-security` | No — install with `[security]` extra | JWT auth and `VsActionSecurity` guard |
+
+---
+
+## Configuration
+
+`VsAgentServer` reads HTTP config via `vs-server` and MCP config via `vs-mcp-agent`. Both use the same `config.ini` file — separated by section.
+
+**HTTP section (from `vs-server`):**
+
+| Key | Default | Description |
+|---|---|---|
+| `server.name` | `vs-agent` | Server name shown in logs and `/` response |
+| `server.version` | `0.1.0` | Version shown in logs and `/` response |
+| `server.host` | `0.0.0.0` | Host to bind |
+| `server.port` | `8000` | HTTP port |
+| `server.reload` | `false` | Enable hot reload (dev only) |
+| `server.workers` | `1` | Number of worker processes |
+| `server.cors_origins` | `*` | Comma-separated allowed CORS origins |
+| `server.ssl_certfile` | — | Path to TLS certificate file |
+| `server.ssl_keyfile` | — | Path to TLS private key file |
+
+**MCP section (from `vs-mcp-agent`):**
+
+| Key | Default | Description |
+|---|---|---|
+| `agent.name` | `vs-agent` | MCP server name |
+| `agent.version` | `0.1.0` | MCP server version |
+| `agent.transport` | `streamable-http` | Transport: `stdio`, `sse`, `streamable-http` |
+| `agent.host` | `0.0.0.0` | MCP host |
+| `agent.port` | `8080` | MCP port |
+| `agent.auth_enabled` | `false` | Enable JWT auth middleware on MCP |
+
+**`config.ini` example:**
+
+```ini
+[server]
+name = my-agent
+version = 1.0.0
+host = 0.0.0.0
+port = 8000
+
+[agent]
+name = my-agent
+version = 1.0.0
+transport = streamable-http
+host = 0.0.0.0
+port = 8080
+auth_enabled = true
+
+[auth]
+secret_key = your-secret-key
+algorithm = HS256
+
+[logging]
+level = INFO
+file_path = ./logs/agent.log
+```
+
+---
+
+## Quick Start
+
+### HTTP + MCP (most common)
+
+```python
+from vs_common.config.vs_ini_config import VsIniConfig
+from vs_common.log.vs_log_manager import VsLogManager
+from vs_common.schema.vs_log_config import VsLogConfig
+from vs_server.server.vs_fast_api_server import VsFastApiServer  # noqa — auto-registers "fastapi"
+from vs_mcp_agent.server.vs_fast_mcp_server import VsFastMcpServer  # noqa — auto-registers "fastmcp"
+from vs_agent.server.vs_agent_server import VsAgentServer
+
+import my_agent.actions  # noqa — registers @action functions
+
+
+def main():
+    config = VsIniConfig("config.ini")
+    VsLogManager.init(VsLogConfig(level=config.get("logging.level", default="INFO")))
+
+    server = VsAgentServer(config, http="fastapi", mcp="fastmcp")
+    server.add_actions()
+    server.run()
+
+
+if __name__ == "__main__":
+    main()
+```
+
+### HTTP only
+
+```python
+server = VsAgentServer(config, http="fastapi")
+server.add_actions()
+server.run()
+```
+
+### MCP only
+
+```python
+from vs_mcp_agent.server.vs_fast_mcp_server import VsFastMcpServer  # noqa — auto-registers "fastmcp"
+
+server = VsAgentServer(config, mcp="fastmcp")
+server.run()
+```
+
+---
+
+## How It All Fits Together
+
+```
+Application Startup
+    └── import VsFastApiServer   # auto-registers "fastapi" into VsServerFactory
+    └── import VsFastMcpServer   # auto-registers "fastmcp" into VsMcpServerFactory
+    └── import my_agent.actions  # @action decorators self-register into VsActionRegistry + VsToolRegistry
+
+VsAgentServer(config, http="fastapi", mcp="fastmcp")
+    ├── VsServerFactory.get("fastapi", config)      → VsFastApiServer
+    └── VsMcpServerFactory.get("fastmcp", config)   → VsFastMcpServer
+
+server.add_actions()
+    ├── reads VsActionRegistry → wires HTTP routes + /capabilities
+    └── VsFastMcpServer already has tools from VsToolRegistry (wired at run())
+
+server.run()
+    ├── MCP server starts on background thread (port 8080)
+    └── HTTP server starts on main thread (port 8000)
+```
+
+---
+
+## VsAgentServer
+
+`VsAgentServer` is the central coordinator. It creates and manages HTTP and MCP server instances via their respective factories.
+
+```python
+from vs_agent.server.vs_agent_server import VsAgentServer
+
+server = VsAgentServer(config, http="fastapi", mcp="fastmcp")
+```
+
+**Constructor parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `config` | `VsBaseConfig` | — | Application config |
+| `http` | `Optional[str]` | `"fastapi"` | HTTP server key. Pass `None` for MCP-only mode. |
+| `mcp` | `Optional[str]` | `None` | MCP server key. Pass `"fastmcp"` to enable MCP. |
+
+At least one of `http` or `mcp` must be specified — both `None` raises `ValueError`.
+
+**Methods:**
+
+| Method | Description |
+|---|---|
+| `add_controller(controller)` | Register an HTTP `@controller` class. Delegates to the HTTP server. |
+| `add_router(router)` | Register a raw router. Delegates to the HTTP server. |
+| `add_websocket(handler)` | Register a `@websocket` handler. Delegates to the HTTP server. |
+| `add_sse(handler)` | Register an `@sse` handler. Delegates to the HTTP server. |
+| `add_actions()` | Wire all `@action` functions to HTTP routes and expose `/capabilities`. |
+| `get_app()` | Return the underlying ASGI app (e.g. FastAPI instance). |
+| `run()` | Start the server(s). MCP runs on a background daemon thread; HTTP runs on the main thread. |
+
+**`mcp` property:**
+
+```python
+server.mcp  # returns the underlying FastMCP instance for advanced configuration
+```
+
+Raises `RuntimeError` if no MCP server is configured.
+
+**All `add_*` methods return `self` for chaining:**
+
+```python
+server = (
+    VsAgentServer(config, http="fastapi", mcp="fastmcp")
+    .add_controller(HealthController())
+    .add_actions()
+)
+server.run()
+```
+
+---
+
+## @action
+
+Registers a function simultaneously as:
+- An MCP tool — in `VsToolRegistry`, picked up by `VsFastMcpServer` when `run()` is called
+- An HTTP endpoint — in `VsActionRegistry`, wired by `server.add_actions()`
+
+```python
+from vs_agent.decorator.vs_action_decorator import action
+from vs_mcp_agent.schema.vs_tool_response import VsToolResponse
+
+@action(
+    name="search_docs",
+    description="Search VS library documentation",
+    path="/v1/docs/search",
+    method="POST",
+    guards=[VsActionSecurity(roles=["user"])],
+)
+async def search_docs(query: str) -> VsToolResponse:
+    results = await _do_search(query)
+    return VsToolResponse(status="success", result=results, summary="Search complete")
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | `str` | Yes | — | MCP tool name and action identifier |
+| `description` | `str` | Yes | — | Shown in MCP tool list and `/capabilities` |
+| `path` | `str` | Yes | — | HTTP endpoint path |
+| `method` | `str` | No | `"POST"` | HTTP method (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`) |
+| `intents` | `List[Intent]` | No | `[]` | Semantic intents for agent routing |
+| `input_schema` | `Dict[str, Any]` | No | `None` | JSON schema for the action input |
+| `guards` | `List[Callable]` | No | `[]` | Guards applied on both HTTP and MCP |
+
+**Import order matters.** `@action` self-registers at import time into both `VsActionRegistry` and `VsToolRegistry`. Import your action modules before calling `server.add_actions()` or `server.run()`.
+
+```python
+import my_agent.actions.search   # noqa — triggers @action registration
+import my_agent.actions.summary  # noqa
+
+server.add_actions()
+server.run()
+```
+
+---
+
+## Authorization with VsActionSecurity
+
+`VsActionSecurity` is a unified guard that works on both HTTP and MCP. It reads the auth context set by `VsSecurityFactory` (HTTP) or `VsMcpAuthMiddleware` (MCP).
+
+```python
+from vs_agent.auth.vs_action_security import VsActionSecurity
+
+@action(
+    name="search_docs",
+    description="Search documentation",
+    path="/v1/docs/search",
+    guards=[VsActionSecurity(roles=["user"])],
+)
+async def search_docs(query: str) -> VsToolResponse:
+    ...
+```
+
+**No roles (auth only):**
+
+```python
+guards=[VsActionSecurity()]  # rejects unauthenticated callers, any role allowed
+```
+
+**Multiple roles (any match):**
+
+```python
+guards=[VsActionSecurity(roles=["admin", "editor"])]  # passes if caller has admin OR editor
+```
+
+**Multiple guards (all must pass, in order):**
+
+```python
+guards=[VsActionSecurity(roles=["admin"]), require_verified_account]
+```
+
+**How guards run per protocol:**
+
+| Protocol | Auth context source | Guard execution |
+|---|---|---|
+| HTTP | `VsSecurityFactory.get()` sets context via FastAPI `Depends` | Guards called in order after auth context is set |
+| MCP | `VsMcpAuthMiddleware` sets context before tool dispatch | Guards called in order before tool function executes |
+
+---
+
+## Lifecycle Hooks
+
+Use lifecycle hooks to run code at server startup and shutdown — creating DB tables, warming caches, closing connections, etc.
+
+### HTTP lifecycle (`vs-server`)
+
+```python
+from vs_server.lifecycle.vs_lifecycle import startup, shutdown
+
+@startup
+async def warm_cache():
+    await VsCacheManager.set("ready", True)
+
+@shutdown
+async def flush_cache():
+    await VsCacheManager.delete("ready")
+```
+
+Register hook modules with `server_registry`:
+
+```python
+from vs_server.decorator.vs_server_registry import server_registry
+
+@server_registry(hooks="my_agent.lifecycle")
+def main():
+    ...
+```
+
+### MCP lifecycle (`vs-mcp-agent`)
+
+```python
+from vs_mcp_agent.lifecycle.vs_mcp_lifecycle import mcp_startup, mcp_shutdown
+
+@mcp_startup
+async def init_mcp_resources():
+    await load_tool_index()
+
+@mcp_shutdown
+async def cleanup_mcp_resources():
+    await close_tool_connections()
+```
+
+Register hook modules with `mcp_server_registry`:
+
+```python
+from vs_mcp_agent.decorator.vs_mcp_server_registry import mcp_server_registry
+
+@mcp_server_registry(hooks="my_agent.mcp_lifecycle")
+def main():
+    ...
+```
+
+When both are used, HTTP and MCP hooks run independently — HTTP hooks fire when the HTTP server starts/stops, MCP hooks fire when the MCP server starts/stops.
+
+---
+
+## HTTP-only Capabilities
+
+For capabilities that should only be available over HTTP, use `@controller` from `vs-server` directly and register via `server.add_controller()`:
+
+```python
+from vs_server.decorator.vs_controller_decorator import controller, get, post
+
+@controller("/v1/internal")
+class InternalController:
+
+    @get("/status")
+    async def status(self):
+        return {"status": "ok"}
+
+server.add_controller(InternalController())
+```
+
+---
+
+## MCP-only Capabilities
+
+For capabilities that should only be available over MCP, use `@tool` from `vs-mcp-agent` directly:
+
+```python
+from vs_mcp_agent.decorator.tool import tool
+from vs_mcp_agent.schema.vs_tool_response import VsToolResponse
+
+@tool(name="internal_tool", description="Internal MCP tool only")
+async def internal_tool(query: str) -> VsToolResponse:
+    ...
+```
+
+These are picked up automatically by `VsFastMcpServer` at `run()` — no extra registration needed.
+
+---
+
+## /capabilities Endpoint
+
+`server.add_actions()` automatically registers a `GET /capabilities` endpoint on the HTTP server. It returns all registered actions with their metadata — used by orchestrators to discover what the agent can do.
+
+**Response:**
+
+```json
+{
+  "actions": [
+    {
+      "name": "search_docs",
+      "description": "Search VS library documentation",
+      "path": "/v1/docs/search",
+      "method": "POST",
+      "intents": [],
+      "input_schema": null
+    }
+  ]
+}
+```
+
+---
+
+## Intents
+
+`Intent` gives each action semantic labels that orchestrators use for routing — matching a user request to the right action without exact string matching.
+
+```python
+from vs_agent.schema.vs_action_schema import Intent
+
+@action(
+    name="search_docs",
+    description="Search VS library documentation",
+    path="/v1/docs/search",
+    intents=[
+        Intent(
+            name="search",
+            description="Find documentation matching a query",
+            examples=["how do I configure logging", "what does VsLogManager do"],
+        )
+    ],
+)
+async def search_docs(query: str) -> VsToolResponse:
+    ...
+```
+
+Intents are returned in `/capabilities` and are available as metadata on `VsActionRegistry` entries.
+
+---
+
+## Error Handling
+
+Exceptions from `@action` functions propagate through both protocols:
+- On HTTP, `vs-server`'s exception handlers convert them to HTTP responses.
+- On MCP, `VsFastMcpServer` returns an error result to the MCP client.
+
+Use exceptions from `vs-server` for standard HTTP error semantics — they are handled automatically:
+
+```python
+from vs_server.schema.exceptions import NotFoundException, ServiceUnavailableException
+
+@action(name="get_doc", description="Get a document", path="/v1/docs/{doc_id}")
+async def get_doc(doc_id: str) -> VsToolResponse:
+    doc = await repo.find(doc_id)
+    if doc is None:
+        raise NotFoundException(f"Document '{doc_id}' not found")
+    return VsToolResponse(status="success", result=doc)
+```
+
+---
+
+## Class Reference
+
+---
+
+### VsAgentServer
+
+Coordinates HTTP and MCP servers. Uses `VsServerFactory` and `VsMcpServerFactory` to resolve server implementations. Supports HTTP-only, MCP-only, or HTTP + MCP modes.
+
+**Constructor:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `config` | `VsBaseConfig` | — | Application config |
+| `http` | `Optional[str]` | `"fastapi"` | HTTP server key registered in `VsServerFactory`. Pass `None` for MCP-only. |
+| `mcp` | `Optional[str]` | `None` | MCP server key registered in `VsMcpServerFactory`. Pass `"fastmcp"` to enable MCP. |
+
+**Methods:**
+
+| Method | Signature | Description |
+|---|---|---|
+| `add_controller` | `add_controller(controller) -> VsAgentServer` | Register an HTTP controller. Requires `http` mode. |
+| `add_router` | `add_router(router) -> VsAgentServer` | Register a raw router. Requires `http` mode. |
+| `add_websocket` | `add_websocket(handler) -> VsAgentServer` | Register a WebSocket handler. Requires `http` mode. |
+| `add_sse` | `add_sse(handler) -> VsAgentServer` | Register an SSE handler. Requires `http` mode. |
+| `add_actions` | `add_actions() -> VsAgentServer` | Wire all `@action` functions to HTTP routes and `/capabilities`. |
+| `get_app` | `get_app() -> Any` | Return the underlying ASGI app. Requires `http` mode. |
+| `run` | `run() -> None` | Start all servers. MCP on daemon thread, HTTP on main thread. |
+
+**Property:**
+
+| Property | Type | Description |
+|---|---|---|
+| `mcp` | `Any` | The underlying FastMCP instance. Raises `RuntimeError` if MCP not configured. |
+
+**Notes:**
+- All `add_*` methods call `_require_http()` internally and raise `RuntimeError` if `http=None`.
+- In HTTP + MCP mode, `run()` starts MCP on a background daemon thread then blocks on the HTTP server.
+- Import `VsFastApiServer` before constructing `VsAgentServer` to ensure `"fastapi"` is registered.
+- Import `VsFastMcpServer` before constructing `VsAgentServer` to ensure `"fastmcp"` is registered.
+
+---
+
+### `@action`
+
+Decorator. Registers a function as both an MCP tool (via `VsToolRegistry`) and an HTTP action (via `VsActionRegistry`). Self-registers at import time.
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | `str` | Yes | — | MCP tool name and action key |
+| `description` | `str` | Yes | — | Shown in MCP tool list and `/capabilities` |
+| `path` | `str` | Yes | — | HTTP endpoint path |
+| `method` | `str` | No | `"POST"` | HTTP method |
+| `intents` | `List[Intent]` | No | `[]` | Semantic intents for orchestrator routing |
+| `input_schema` | `Dict[str, Any]` | No | `None` | JSON schema for the action input |
+| `guards` | `List[Callable]` | No | `[]` | Applied on both HTTP and MCP, in order |
+
+**Notes:**
+- Each `name` must be unique across all `@action` registrations. Duplicate names raise `ValueError`.
+- `method` is HTTP-only — MCP tools have no HTTP method concept.
+- `guards` must be async callables.
+
+---
+
+### VsActionSecurity
+
+Guard class for unified HTTP + MCP authorization. Reads from the auth context set by whichever protocol is active.
+
+**Constructor:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `roles` | `Optional[List[str]]` | `[]` | Required roles. Caller must have at least one. Empty list = any authenticated caller. |
+
+**Behaviour:**
+
+| Condition | Result |
+|---|---|
+| No auth context | Raises `PermissionError("Unauthenticated request")` |
+| Auth context present, no roles required | Passes |
+| Auth context present, caller has required role | Passes |
+| Auth context present, caller lacks required role | Raises `PermissionError` |
+
+**Notes:**
+- On HTTP, auth context is set by `VsSecurityFactory.get()` (from `vs-security`).
+- On MCP, auth context is set by `VsMcpAuthMiddleware` (from `vs-mcp-agent`).
+- `VsActionSecurity` reads from the same context variable regardless of protocol.
+
+---
+
+### VsActionRegistry
+
+Class-level registry of all `@action`-registered functions. Thread-safe.
+
+**Methods:**
+
+| Method | Signature | Description |
+|---|---|---|
+| `register` | `register(name, description, path, method, intents, input_schema, guards, fn) -> None` | Register an action. Raises `ValueError` if name is already registered. |
+| `get_all` | `get_all() -> Dict[str, _ActionEntry]` | Returns a snapshot of all registered actions. |
+
+**Notes:**
+- `@action` calls `VsActionRegistry.register()` and `VsToolRegistry.register_fn()` at decoration time.
+- `server.add_actions()` reads from `VsActionRegistry.get_all()` to wire HTTP routes.
+
+---
+
+### Intent
+
+Pydantic model. Semantic label for an action — used by orchestrators for routing.
+
+**Fields:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | `str` | Yes | Short intent identifier |
+| `description` | `str` | Yes | What this intent means |
+| `examples` | `Optional[List[str]]` | No | Example user phrases that trigger this intent |
+
+---
+
+### ActionCapability
+
+Pydantic model. Metadata for a single action as returned by `/capabilities`.
+
+**Fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `str` | Action name |
+| `description` | `str` | Action description |
+| `path` | `str` | HTTP endpoint path |
+| `method` | `str` | HTTP method |
+| `intents` | `List[Intent]` | Semantic intents |
+| `input_schema` | `Optional[Dict[str, Any]]` | JSON schema for input |
+
+---
+
+### CapabilitiesResponse
+
+Pydantic model. Response from `GET /capabilities`.
+
+**Fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `actions` | `List[ActionCapability]` | All registered actions |

vs_agent-0.1.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+vs_agent/__init__.py,sha256=3yuN4M5I9y2QMcXQ5hhqE73XwH2O97mIH3QaJ-acnS4,94
+vs_agent/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vs_agent/auth/vs_action_security.py,sha256=jj6Hb8_CNO_1lCYoz9WsbfiJQ_V4ifz9YoqAoeoYYYw,502
+vs_agent/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vs_agent/client/vs_peer_agent_client.py,sha256=i_62CO4d-fLr47cqnLQc1RIMZX5I5DBOJKc6hTVscr0,2404
+vs_agent/decorator/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vs_agent/decorator/vs_action_decorator.py,sha256=MM2Wk9vsLaTV8VtEBVBrcXH240oV5oWsWw5rGVLi2lY,801
+vs_agent/discovery/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vs_agent/discovery/vs_peer_agent_registry.py,sha256=xuiiJPNcogWmr51S8qRB_2N1DfXbhDGfU7VT7wzGhN4,2284
+vs_agent/discovery/vs_peer_agent_scheduler.py,sha256=aGfOePuTjEezZitCdr8r3HT251wTMETXgwLrq2EuSAU,1207
+vs_agent/discovery/vs_peer_capability_loader.py,sha256=_BK0vsRTgZh6hgfN2klpvCZBZDaDCZmTtGjZoiBk-8E,3304
+vs_agent/registry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vs_agent/registry/vs_action_registry.py,sha256=agQ43fofEAwkWtjX9UZe5wLpgFO4GVoOKS8mZR1e-xo,1331
+vs_agent/schema/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vs_agent/schema/vs_action_schema.py,sha256=Se0XX3kYmDylYok2cn3yJ9jVPCjdXWrFIq6Va45nt64,434
+vs_agent/server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vs_agent/server/vs_agent_server.py,sha256=nVeUmkcfGnI1bz9VFJ_HP7-NFymxHjsWMdfuZbEwya4,6397
+vs_agent-0.1.1.dist-info/METADATA,sha256=j2ZsFytzlrpFaG-AG2LSbjOM9j5Q8i0IIUAoiGXa5Sc,21506
+vs_agent-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+vs_agent-0.1.1.dist-info/top_level.txt,sha256=lzOLrUrjfBxn4S1Evc_osgkXJpPbw62uonkfPrfx6uM,9
+vs_agent-0.1.1.dist-info/RECORD,,

vs_agent-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vs_agent-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+vs_agent