aethergraph 0.1.0a1__py3-none-any.whl → 0.1.0a3__py3-none-any.whl

aethergraph/services/llm/providers.py

@@ -1,3 +1,5 @@
 from typing import Literal
 
-Provider = Literal["openai", "azure", "anthropic", "google", "openrouter", "lmstudio", "ollama"]
+Provider = Literal[
+    "openai", "azure", "anthropic", "google", "openrouter", "lmstudio", "ollama", "dummy"
+]  # dummy for testing

aethergraph/services/llm/types.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass
+from typing import Any, Literal
+
+ChatOutputFormat = Literal["text", "json_object", "json_schema"]
+
+ImageFormat = Literal["png", "jpeg", "webp"]
+ImageResponseFormat = Literal["b64_json", "url"]  # url only for dall-e models typically
+
+
+@dataclass(frozen=True)
+class JsonSchemaSpec:
+    name: str
+    schema: dict[str, Any]
+    strict: bool = True
+
+
+@dataclass(frozen=True)
+class ImageInput:
+    data: bytes | None = None
+    b64: str | None = None  # base64 without data: prefix
+    mime_type: str | None = None
+    url: str | None = None  # http(s) url OR provider file_uri
+    is_file_uri: bool = False  # Gemini file URIs
+
+
+class LLMUnsupportedFeatureError(RuntimeError):
+    def __init__(self, provider: str, model: str | None, feature: str, detail: str | None = None):
+        msg = f"Provider '{provider}' / model '{model or '?'}' does not support: {feature}"
+        if detail:
+            msg += f" ({detail})"
+        super().__init__(msg)
+
+
+@dataclass
+class GeneratedImage:
+    # Exactly one of these is typically present.
+    b64: str | None = None
+    url: str | None = None
+    mime_type: str | None = None
+    revised_prompt: str | None = None
+
+
+@dataclass
+class ImageGenerationResult:
+    images: list[GeneratedImage]
+    usage: dict[str, int]  # often empty for image endpoints
+    raw: dict[str, Any] | None = None

aethergraph/services/llm/utils.py

@@ -0,0 +1,284 @@
+import base64
+from collections.abc import Sequence
+import json
+import re
+from typing import Any, Literal
+
+from aethergraph.services.llm.types import ImageInput
+
+ChatOutputFormat = Literal["text", "json_object", "json_schema"]
+
+
+def _is_data_url(s: str) -> bool:
+    return isinstance(s, str) and s.startswith("data:") and ";base64," in s
+
+
+def _image_bytes_to_b64(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def _data_url_to_b64_and_mime(url: str) -> tuple[str, str]:
+    head, b64 = url.split(",", 1)
+    mime = head.split(";")[0].split(":", 1)[1]
+    return b64, mime
+
+
+def _ensure_b64(img: ImageInput) -> tuple[str, str]:
+    if img.b64 and img.mime_type:
+        return img.b64, img.mime_type
+    if img.url and _is_data_url(img.url):
+        return _data_url_to_b64_and_mime(img.url)
+    if img.data and img.mime_type:
+        import base64
+
+        return base64.b64encode(img.data).decode("ascii"), img.mime_type
+    raise ValueError("ImageInput must have (b64+mime_type) or (data+mime_type) or a data: URL")
+
+
+def _normalize_messages(messages: Sequence[dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    Normalize many common message shapes into:
+      {"role": "...", "parts": [{"type":"text","text":...} | {"type":"image","image": ImageInput}]}
+    Supports:
+      - {"role","content":"text"}
+      - ChatCompletions multimodal image_url parts
+      - Responses input_image parts
+      - Anthropic image source blocks
+    """
+    out: list[dict[str, Any]] = []
+    for m in messages:
+        role = (m.get("role") or "user").lower()
+        content = m.get("content")
+        parts: list[dict[str, Any]] = []
+
+        if isinstance(content, str):
+            parts.append({"type": "text", "text": content})
+        elif isinstance(content, list):
+            for p in content:
+                if not isinstance(p, dict):
+                    continue
+                t = p.get("type")
+
+                if t in ("text", "input_text", "output_text"):
+                    parts.append({"type": "text", "text": p.get("text", "")})
+                    continue
+
+                if t == "image_url":
+                    iu = p.get("image_url") or {}
+                    url = iu.get("url") or p.get("url")
+                    if isinstance(url, str):
+                        parts.append({"type": "image", "image": ImageInput(url=url)})
+                    continue
+
+                if t == "input_image":
+                    url = p.get("image_url")
+                    if isinstance(url, str):
+                        parts.append({"type": "image", "image": ImageInput(url=url)})
+                    continue
+
+                if t == "image":
+                    src = p.get("source") or {}
+                    if src.get("type") == "base64":
+                        parts.append(
+                            {
+                                "type": "image",
+                                "image": ImageInput(
+                                    b64=src.get("data"), mime_type=src.get("media_type")
+                                ),
+                            }
+                        )
+                    elif src.get("type") == "url":
+                        parts.append({"type": "image", "image": ImageInput(url=src.get("url"))})
+                    continue
+
+        out.append({"role": role, "parts": parts})
+    return out
+
+
+def _has_images(norm: Sequence[dict[str, Any]]) -> bool:
+    return any(p.get("type") == "image" for m in norm for p in m.get("parts", []))
+
+
+def _strip_code_fences(s: str) -> str:
+    s = s.strip()
+    if s.startswith("```"):
+        s = re.sub(r"^```[a-zA-Z0-9_-]*\s*", "", s)
+        s = re.sub(r"\s*```$", "", s)
+    return s.strip()
+
+
+def _extract_json_text(text: str) -> str:
+    t = _strip_code_fences(text)
+    if not t:
+        return t
+    if t[0] in "{[":
+        return t
+    m = re.search(r"(\{.*\}|\[.*\])", t, flags=re.DOTALL)
+    return m.group(1).strip() if m else t
+
+
+def _validate_json_schema(obj: Any, schema: dict[str, Any]) -> None:
+    try:
+        import jsonschema  # type: ignore
+    except Exception:
+        return
+    jsonschema.validate(instance=obj, schema=schema)
+
+
+def _ensure_system_json_directive(
+    messages: list[dict[str, Any]], *, schema: dict[str, Any] | None
+) -> list[dict[str, Any]]:
+    directive = "Return ONLY valid JSON. No markdown, no commentary."
+    if schema is not None:
+        directive += "\nThe JSON MUST conform to this JSON Schema:\n" + json.dumps(
+            schema, ensure_ascii=False
+        )
+    return [{"role": "system", "content": directive}] + list(messages)
+
+
+def _message_content_has_images(messages: list[dict[str, Any]]) -> bool:
+    for m in messages:
+        c = m.get("content")
+        if isinstance(c, list):
+            for p in c:
+                if isinstance(p, dict) and p.get("type") in ("image_url", "input_image", "image"):
+                    return True
+    return False
+
+
+def _to_anthropic_blocks(content: Any) -> list[dict[str, Any]]:
+    """
+    Accept:
+      - str -> [{"type":"text","text":...}]
+      - OpenAI multimodal list -> convert data URLs -> anthropic base64 image blocks
+      - Anthropic blocks -> passthrough
+    """
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}]
+
+    if isinstance(content, list):
+        blocks: list[dict[str, Any]] = []
+        for p in content:
+            if not isinstance(p, dict):
+                continue
+            t = p.get("type")
+            if t in ("text", "input_text", "output_text"):
+                blocks.append({"type": "text", "text": p.get("text", "")})
+            elif t == "image" and "source" in p:
+                blocks.append(p)
+            elif t in ("image_url", "input_image"):
+                url = None
+                if t == "image_url":
+                    url = (p.get("image_url") or {}).get("url") or p.get("url")
+                else:
+                    url = p.get("image_url")
+                if isinstance(url, str) and _is_data_url(url):
+                    b64, mime = _data_url_to_b64_and_mime(url)
+                    blocks.append(
+                        {
+                            "type": "image",
+                            "source": {"type": "base64", "media_type": mime, "data": b64},
+                        }
+                    )
+                elif isinstance(url, str):
+                    raise RuntimeError(
+                        "Anthropic vision: provide data: URLs (base64) for images (no remote fetch in client)."
+                    )
+        return blocks
+
+    return [{"type": "text", "text": str(content)}]
+
+
+def _to_gemini_parts(content: Any) -> list[dict[str, Any]]:
+    """
+    Gemini REST generateContent supports:
+      - {"text": "..."}
+      - {"inline_data": {"mime_type": "...", "data": "<base64>"}}
+    """
+    if isinstance(content, str):
+        return [{"text": content}]
+
+    if isinstance(content, list):
+        parts: list[dict[str, Any]] = []
+        for p in content:
+            if not isinstance(p, dict):
+                continue
+            t = p.get("type")
+            if t in ("text", "input_text", "output_text"):
+                parts.append({"text": p.get("text", "")})
+            elif t in ("image_url", "input_image"):
+                url = None
+                if t == "image_url":
+                    url = (p.get("image_url") or {}).get("url") or p.get("url")
+                else:
+                    url = p.get("image_url")
+                if isinstance(url, str) and _is_data_url(url):
+                    b64, mime = _data_url_to_b64_and_mime(url)
+                    parts.append({"inline_data": {"mime_type": mime, "data": b64}})
+                elif isinstance(url, str):
+                    raise RuntimeError(
+                        "Gemini vision: provide data: URLs (base64) or file_uri; remote http(s) URLs not accepted inline."
+                    )
+        return parts
+
+    return [{"text": str(content)}]
+
+
+def _normalize_openai_responses_input(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    Make OpenAI Responses input robust:
+      - If content is str: keep as-is
+      - If content is OpenAI chat multimodal parts (text/image_url): convert to input_text/input_image
+      - If already input_text/input_image: passthrough
+    """
+    out: list[dict[str, Any]] = []
+    for m in messages:
+        role = m.get("role", "user")
+        c = m.get("content")
+
+        if isinstance(c, str):
+            out.append({"role": role, "content": c})
+            continue
+
+        if isinstance(c, list):
+            blocks: list[dict[str, Any]] = []
+            for p in c:
+                if not isinstance(p, dict):
+                    continue
+                t = p.get("type")
+                if t in ("input_text", "input_image"):
+                    blocks.append(p)
+                elif t in ("text", "output_text"):
+                    blocks.append({"type": "input_text", "text": p.get("text", "")})
+                elif t == "image_url":
+                    url = (p.get("image_url") or {}).get("url") or p.get("url")
+                    if isinstance(url, str):
+                        blocks.append({"type": "input_image", "image_url": url})
+                else:
+                    # ignore unknown part types
+                    pass
+            out.append({"role": role, "content": blocks})
+            continue
+
+        out.append({"role": role, "content": str(c)})
+    return out
+
+
+def _normalize_base_url_no_trailing_slash(url: str) -> str:
+    return (url or "").strip().rstrip("/")
+
+
+def _azure_images_generations_url(endpoint: str, deployment: str, api_version: str) -> str:
+    # endpoint example: https://<resource>.openai.azure.com
+    ep = _normalize_base_url_no_trailing_slash(endpoint)
+    return f"{ep}/openai/deployments/{deployment}/images/generations?api-version={api_version}"
+
+
+def _guess_mime_from_format(fmt: str) -> str:
+    if fmt == "png":
+        return "image/png"
+    if fmt == "jpeg":
+        return "image/jpeg"
+    if fmt == "webp":
+        return "image/webp"
+    return "application/octet-stream"

aethergraph/services/logger/std.py

@@ -123,6 +123,9 @@ class StdLoggerService(LoggerService):
     def for_inspect(self) -> logging.Logger:
         return self.for_namespace("inspect")
 
+    def for_channel(self) -> logging.Logger:
+        return self.for_namespace("channel")
+
     def for_scheduler(self) -> logging.Logger:
         return self.for_namespace("scheduler")
 

aethergraph/services/mcp/__init__.py

@@ -0,0 +1,9 @@
+from .http_client import HttpMCPClient
+from .stdio_client import StdioMCPClient
+from .ws_client import WsMCPClient
+
+__all__ = [
+    "HttpMCPClient",
+    "StdioMCPClient",
+    "WsMCPClient",
+]

aethergraph/services/mcp/http_client.py

@@ -10,6 +10,44 @@ from aethergraph.contracts.services.mcp import MCPClientProtocol, MCPResource, M
 
 
 class HttpMCPClient(MCPClientProtocol):
+    """
+    Initialize the HTTP client service with base URL, headers, and timeout.
+
+    This constructor sets up the base URL for all requests, applies default and custom headers,
+    and configures the request timeout. It also initializes internal state for the asynchronous
+    HTTP client and concurrency control.
+
+    Examples:
+        Basic usage with default headers:
+        ```python
+        from aethergraph.services.mcp import HttpMCPClient
+        client = HttpMCPClient("https://api.example.com")
+        ```
+
+        Custom headers and timeout:
+        ```python
+        from aethergraph.services.mcp import HttpMCPClient
+        client = HttpMCPClient(
+            "https://api.example.com",
+            headers={"Authorization": "Bearer <token>"},
+            timeout=30.0
+        )
+        ```
+
+    Args:
+        base_url: The root URL for all HTTP requests (e.g., "https://api.example.com").
+        headers: Optional dictionary of additional HTTP headers to include with each request.
+        The "Content-Type: application/json" header is always set by default.
+        timeout: The maximum time (in seconds) to wait for a response before timing out.
+
+    Returns:
+        None: Initializes the HttpMCPClient instance.
+
+    Notes:
+        - Ensure that the base_url does not have a trailing slash; it will be added automatically.
+        - The client uses asynchronous HTTP requests for non-blocking operations.
+    """
+
     def __init__(
         self,
         base_url: str,