amsdal_ml 0.1.0__tar.gz → 0.1.1__tar.gz

{amsdal_ml-0.1.0 → amsdal_ml-0.1.1}/.gitignore

@@ -29,5 +29,8 @@ Thumbs.db
 !.env.example  
 
 
-transactions/
-migrations/
+/transactions/
+/migrations/
+/models/
+/fixtures/
+/static/

{amsdal_ml-0.1.0 → amsdal_ml-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amsdal_ml
-Version: 0.1.0
+Version: 0.1.1
 Summary: amsdal_ml plugin for AMSDAL Framework
 Requires-Python: >=3.11
 Requires-Dist: aiohttp==3.12.15

amsdal_ml-0.1.1/amsdal_ml/__about__.py

@@ -0,0 +1 @@
+__version__ = '0.1.1'

{amsdal_ml-0.1.0 → amsdal_ml-0.1.1}/amsdal_ml/agents/agent.py

@@ -6,10 +6,13 @@ from collections.abc import AsyncIterator
 from collections.abc import Iterator
 from typing import Any
 from typing import Literal
+from typing import Optional
 
 from pydantic import BaseModel
 from pydantic import Field
 
+from amsdal_ml.fileio.base_loader import FileAttachment
+
 
 class AgentMessage(BaseModel):
     role: Literal["SYSTEM", "USER", "ASSISTANT"]
@@ -24,16 +27,37 @@ class AgentOutput(BaseModel):
 
 class Agent(ABC):
     @abstractmethod
-    async def arun(self, user_query: str) -> AgentOutput: ...
-    @abstractmethod
-    async def astream(self, user_query: str) -> AsyncIterator[str]:
-        """Yield streamed chunks for the given query."""
-        raise NotImplementedError
+    async def arun(
+        self,
+        user_query: str,
+        *,
+        attachments: Optional[list[FileAttachment]] = None,
+    ) -> AgentOutput:
+        ...
 
-    def run(self, user_query: str) -> AgentOutput:
+    @abstractmethod
+    async def astream(
+        self,
+        user_query: str,
+        *,
+        attachments: Optional[list[FileAttachment]] = None,
+    ) -> AsyncIterator[str]:
+        ...
+
+    def run(
+        self,
+        user_query: str,
+        *,
+        attachments: Optional[list[FileAttachment]] = None,
+    ) -> AgentOutput:
         msg = "This agent is async-only. Use arun()."
         raise NotImplementedError(msg)
 
-    def stream(self, user_query: str) -> Iterator[str]:
+    def stream(
+        self,
+        user_query: str,
+        *,
+        attachments: Optional[list[FileAttachment]] = None,
+    ) -> Iterator[str]:
         msg = "This agent is async-only. Use astream()."
         raise NotImplementedError(msg)

{amsdal_ml-0.1.0 → amsdal_ml-0.1.1}/amsdal_ml/agents/default_qa_agent.py

@@ -13,6 +13,7 @@ from typing import no_type_check
 from amsdal_ml.agents.agent import Agent
 from amsdal_ml.agents.agent import AgentOutput
 from amsdal_ml.agents.promts import get_prompt
+from amsdal_ml.fileio.base_loader import FileAttachment
 from amsdal_ml.mcp_client.base import ToolClient
 from amsdal_ml.mcp_client.base import ToolInfo
 from amsdal_ml.ml_models.models import MLModel
@@ -30,6 +31,9 @@ _FINAL_RE = re.compile(
     r"Final Answer:\s*(?P<answer>.+)",
     re.DOTALL | re.IGNORECASE,
 )
+# ---------- constants ----------
+
+_MAX_PARSE_RETRIES = 5
 
 
 
@@ -186,11 +190,11 @@ class DefaultQAAgent(Agent):
             return str(content)
 
     # ---------- core run ----------
-    def run(self, _user_query: str) -> AgentOutput:
+    def run(self, user_query: str, *, attachments: list[FileAttachment] | None = None) -> AgentOutput:
         msg = "DefaultQAAgent is async-only for now. Use arun()."
         raise NotImplementedError(msg)
 
-    async def _run_async(self, user_query: str) -> AgentOutput:
+    async def _run_async(self, user_query: str, *, attachments: list[FileAttachment] | None = None) -> AgentOutput:
         if self._tool_clients and not self._tools_index_built:
             await self._build_clients_index()
 
@@ -198,10 +202,12 @@ class DefaultQAAgent(Agent):
         used_tools: list[str] = []
         parse_retries = 0
 
+
         for _ in range(self.max_steps):
             prompt = self._react_text(user_query, scratch)
-            out = await self.model.ainvoke(prompt)
-
+            out = await self.model.ainvoke(prompt, attachments=attachments)
+            print("Model output:", out)  # noqa: T201
+            print('promt:', prompt)  # noqa: T201
             m_final = _FINAL_RE.search(out or "")
             if m_final:
                 return AgentOutput(
@@ -213,7 +219,7 @@ class DefaultQAAgent(Agent):
             m_tool = _TOOL_CALL_RE.search(out or "")
             if not m_tool:
                 parse_retries += 1
-                if self.on_parse_error == ParseErrorMode.RAISE or parse_retries >= 1:
+                if self.on_parse_error == ParseErrorMode.RAISE or parse_retries >= _MAX_PARSE_RETRIES:
                     msg = (
                         "Invalid ReAct output. Expected EXACT format (Final or Tool-call). "
                         f"Got:\n{out}"
@@ -221,6 +227,7 @@ class DefaultQAAgent(Agent):
                     raise ValueError(
                         msg
                     )
+
                 scratch += (
                     "\nThought: Previous output violated the strict format. "
                     "Reply again using EXACTLY one of the two specified formats.\n"
@@ -237,7 +244,7 @@ class DefaultQAAgent(Agent):
                     raise ValueError(msg)
             except Exception as e:
                 parse_retries += 1
-                if self.on_parse_error == ParseErrorMode.RAISE or parse_retries >= 1:
+                if self.on_parse_error == ParseErrorMode.RAISE or parse_retries >= _MAX_PARSE_RETRIES:
                     msg = f"Invalid Action Input JSON: {raw_input!r} ({e})"
                     raise ValueError(msg) from e
                 scratch += (
@@ -250,6 +257,7 @@ class DefaultQAAgent(Agent):
 
             try:
                 result = await tool.run(args, context=None, convert_result=True)
+                print("Similarity search result:", result)  # noqa: T201
             except Exception as e:
                 # unified error payload
                 err = {
@@ -276,12 +284,12 @@ class DefaultQAAgent(Agent):
         return self._stopped_response(used_tools)
 
     # ---------- public APIs ----------
-    async def arun(self, user_query: str) -> AgentOutput:
-        return await self._run_async(user_query)
+    async def arun(self, user_query: str, *, attachments: list[FileAttachment] | None = None) -> AgentOutput:
+        return await self._run_async(user_query, attachments=attachments)
 
     # ---------- streaming ----------
     @no_type_check
-    async def astream(self, user_query: str) -> AsyncIterator[str]:
+    async def astream(self, user_query: str, *, attachments: list[FileAttachment] | None = None) -> AsyncIterator[str]:
         if self._tool_clients and not self._tools_index_built:
             await self._build_clients_index()
 
@@ -296,7 +304,7 @@ class DefaultQAAgent(Agent):
 
             # Normalize model.astream: it might be an async iterator already,
             # or a coroutine (or nested coroutines) that resolves to one.
-            _val = self.model.astream(prompt)
+            _val = self.model.astream(prompt, attachments=attachments)
             while inspect.iscoroutine(_val):
                 _val = await _val
 
@@ -320,7 +328,7 @@ class DefaultQAAgent(Agent):
             m_tool = _TOOL_CALL_RE.search(buffer or "")
             if not m_tool:
                 parse_retries += 1
-                if self.on_parse_error == ParseErrorMode.RAISE or parse_retries >= 1:
+                if self.on_parse_error == ParseErrorMode.RAISE or parse_retries >= _MAX_PARSE_RETRIES:
                     msg = f"Invalid ReAct output (stream). Expected EXACT format. Got:\n{buffer}"
                     raise ValueError(msg)
                 scratch += (
@@ -339,7 +347,7 @@ class DefaultQAAgent(Agent):
                     raise ValueError(msg)
             except Exception as e:
                 parse_retries += 1
-                if self.on_parse_error == ParseErrorMode.RAISE or parse_retries >= 1:
+                if self.on_parse_error == ParseErrorMode.RAISE or parse_retries >= _MAX_PARSE_RETRIES:
                     msg = f"Invalid Action Input JSON: {raw_input!r} ({e})"
                     raise ValueError(msg) from e
                 scratch += (

{amsdal_ml-0.1.0 → amsdal_ml-0.1.1}/amsdal_ml/agents/promts/react_chat.prompt

@@ -21,7 +21,16 @@ RULES
 - `Action Input` MUST be a valid ONE-LINE JSON object (e.g. {{"a": 1, "b": 2}}).
 - Do NOT add anything before/after the block.
 - Do NOT print "Observation". The system will add it after tool execution.
-
+- You CAN read and use any attached files provided by the platform (including PDFs). Do not claim inability to view files.
+- Prefer not to use tools when the answer is fully supported by the user’s message and/or attached files. Use a tool only if it materially improves accuracy or retrieves missing facts.
+- If information is insufficient, answer concisely with: “I don’t have enough data to answer.”
+- Be deterministic and concise. No preambles, no meta-commentary, no Markdown.
+- Numbers: preserve exact figures, units, and percentages; do not round unless asked.
+- If you choose a tool:
+  - Use exactly one tool per step.
+  - The Action Input MUST be a single-line valid JSON object that matches the tool’s schema.
+  - If a tool errors or returns nothing useful, switch to the other format and produce a Final Answer.
+  
 PREVIOUS CONVERSATION
 --------------------
 {chat_history}

{amsdal_ml-0.1.0 → amsdal_ml-0.1.1}/amsdal_ml/agents/retriever_tool.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import logging
+import sys
 from typing import Any
 from typing import Optional
 
@@ -9,6 +11,14 @@ from pydantic import Field
 
 from amsdal_ml.ml_retrievers.openai_retriever import OpenAIRetriever
 
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s [%(levelname)s] %(message)s',
+    handlers=[
+        logging.FileHandler("server2.log"),
+        logging.StreamHandler(sys.stdout)
+    ]
+)
 
 class RetrieverArgs(BaseModel):
     query: str = Field(..., description='User search query')
@@ -20,13 +30,22 @@ class RetrieverArgs(BaseModel):
 _retriever = OpenAIRetriever()
 
 
-async def retriever_search(args: RetrieverArgs) -> list[dict[str, Any]]:
+async def retriever_search(
+    query: str = Field(..., description='User search query'),
+    k: int = 5,
+    include_tags: Optional[list[str]] = None,
+    exclude_tags: Optional[list[str]] = None,
+) -> list[dict[str, Any]]:
+    logging.info(
+        f"retriever_search called with query={query}, k={k}, include_tags={include_tags}, exclude_tags={exclude_tags}"
+    )
     chunks = await _retriever.asimilarity_search(
-        query=args.query,
-        k=args.k,
-        include_tags=args.include_tags,
-        exclude_tags=args.exclude_tags,
+        query=query,
+        k=k,
+        include_tags=include_tags,
+        exclude_tags=exclude_tags,
     )
+    logging.info(f"retriever_search found {len(chunks)} chunks: {chunks}")
     out: list[dict[str, Any]] = []
     for c in chunks:
         if hasattr(c, 'model_dump'):
@@ -42,7 +61,7 @@ async def retriever_search(args: RetrieverArgs) -> list[dict[str, Any]]:
 
 retriever_tool = Tool.from_function(
     retriever_search,
-    name='retriever.search',
+    name='search',
     description='Semantic search in knowledge base (OpenAI embeddings)',
     structured_output=True,
 )

amsdal_ml-0.1.1/amsdal_ml/fileio/base_loader.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Any
+from typing import BinaryIO
+from typing import Optional
+
+from pydantic import BaseModel
+
+PLAIN_TEXT = "plain_text"
+FILE_ID = "file_id"
+
+
+class FileData(BaseModel):
+    name: str
+    size: int | None = None
+    mime: Optional[str] = None
+
+
+@dataclass
+class FileAttachment:
+    type: str  # one of: PLAIN_TEXT, FILE_ID
+    content: Any
+    metadata: dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        if self.metadata is None:
+            self.metadata = {}
+
+
+@dataclass
+class FileItem:
+    file: BinaryIO
+    filename: str | None = None
+    filedata: FileData | None = None
+
+    @staticmethod
+    def from_path(path: str, *, filedata: FileData | None = None) -> FileItem:
+        # Caller is responsible for lifecycle; loaders may close after upload.
+        f = open(path, "rb")
+        return FileItem(file=f, filename=path.split("/")[-1], filedata=filedata)
+
+    @staticmethod
+    def from_bytes(data: bytes, *, filename: str | None = None, filedata: FileData | None = None) -> FileItem:
+        import io
+        return FileItem(file=io.BytesIO(data), filename=filename, filedata=filedata)
+
+    @staticmethod
+    def from_str(text: str, *, filename: str | None = None, filedata: FileData | None = None) -> FileItem:
+        import io
+        return FileItem(file=io.BytesIO(text.encode("utf-8")), filename=filename, filedata=filedata)
+
+
+class BaseFileLoader(ABC):
+    @abstractmethod
+    async def load(self, item: FileItem) -> FileAttachment:
+        """Upload a single file and return an attachment reference."""
+
+    @abstractmethod
+    async def load_batch(self, items: list[FileItem]) -> list[FileAttachment]:
+        """Upload multiple files; input and output are lists for simplicity."""

amsdal_ml-0.1.1/amsdal_ml/fileio/openai_loader.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import asyncio
+import io
+import logging
+from collections.abc import Sequence
+from typing import Any
+from typing import BinaryIO
+from typing import Literal
+
+from openai import AsyncOpenAI
+
+from amsdal_ml.fileio.base_loader import FILE_ID
+from amsdal_ml.fileio.base_loader import BaseFileLoader
+from amsdal_ml.fileio.base_loader import FileAttachment
+from amsdal_ml.fileio.base_loader import FileData
+from amsdal_ml.fileio.base_loader import FileItem
+
+logger = logging.getLogger(__name__)
+
+AllowedPurpose = Literal["assistants", "batch", "fine-tune", "vision", "user_data", "evals"]
+
+
+class OpenAIFileLoader(BaseFileLoader):
+    """
+    Loader which uploads files into OpenAI Files API and returns openai_file_id.
+    """
+
+    def __init__(self, client: AsyncOpenAI, *, purpose: AllowedPurpose = "assistants") -> None:
+        self.client = client
+        self.purpose: AllowedPurpose = purpose  # mypy: Literal union, matches SDK
+
+    async def _upload_one(self, file: BinaryIO, *, filename: str | None, filedata: FileData | None) -> FileAttachment:
+        try:
+            if hasattr(file, "seek"):
+                file.seek(0)
+        except Exception as exc:  # pragma: no cover
+            logger.debug("seek(0) failed for %r: %s", filename or file, exc)
+
+        buf = file if isinstance(file, io.BytesIO) else io.BytesIO(file.read())
+
+        up = await self.client.files.create(file=(filename or "upload.bin", buf), purpose=self.purpose)
+
+        meta: dict[str, Any] = {
+            "filename": filename,
+            "provider": "openai",
+            "file": {
+                "id": up.id,
+                "bytes": getattr(up, "bytes", None),
+                "purpose": getattr(up, "purpose", self.purpose),
+                "created_at": getattr(up, "created_at", None),
+                "status": getattr(up, "status", None),
+                "status_details": getattr(up, "status_details", None),
+            },
+        }
+        if filedata is not None:
+            meta["filedata"] = filedata.model_dump()
+
+        return FileAttachment(type=FILE_ID, content=up.id, metadata=meta)
+
+    async def load(self, item: FileItem) -> FileAttachment:
+        return await self._upload_one(item.file, filename=item.filename, filedata=item.filedata)
+
+    async def load_batch(self, items: Sequence[FileItem]) -> list[FileAttachment]:
+        tasks = [
+            asyncio.create_task(self._upload_one(it.file, filename=it.filename, filedata=it.filedata))
+            for it in items
+        ]
+        return await asyncio.gather(*tasks)

{amsdal_ml-0.1.0 → amsdal_ml-0.1.1}/amsdal_ml/mcp_client/stdio_client.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import asyncio
+import base64
 from collections.abc import Iterable
 from contextlib import AsyncExitStack
 from typing import Any
 
+from amsdal_utils.config.manager import AmsdalConfigManager
 from mcp import ClientSession
 from mcp import StdioServerParameters
 from mcp.client.stdio import stdio_client
@@ -19,7 +21,14 @@ class StdioClient(ToolClient):
     MCP over STDIO client.
     """
 
-    def __init__(self, alias: str, module_or_cmd: str, *args: str, persist_session: bool = True):
+    def __init__(
+    self,
+    alias: str,
+    module_or_cmd: str,
+    *args: str,
+    persist_session: bool = True,
+    send_amsdal_config: bool = True,
+    ):
         self.alias = alias
         if module_or_cmd in ("python", "python3"):
             self._command = module_or_cmd
@@ -27,7 +36,9 @@ class StdioClient(ToolClient):
         else:
             self._command = "python"
             self._args = ["-m", module_or_cmd]
-
+        if send_amsdal_config:
+            self._args.append("--amsdal-config")
+            self._args.append(self._build_amsdal_config_arg())
         self._persist = persist_session
         self._lock = asyncio.Lock()
         self._stack: AsyncExitStack | None = None
@@ -115,6 +126,7 @@ class StdioClient(ToolClient):
                 rx, tx = await stack.enter_async_context(stdio_client(params))
                 s = await stack.enter_async_context(ClientSession(rx, tx))
                 await s.initialize()
+                print("Calling tool:", tool_name, "with args:", args)  # noqa: T201
                 res = await self._call_with_timeout(s.call_tool(tool_name, args), timeout=timeout)
                 return getattr(res, "content", res)
 
@@ -128,3 +140,11 @@ class StdioClient(ToolClient):
             s = await self._ensure_session()
             res = await self._call_with_timeout(s.call_tool(tool_name, args), timeout=timeout)
             return getattr(res, "content", res)
+
+    def _build_amsdal_config_arg(self) -> str:
+        """
+        Build a JSON string argument representing the current Amsdal configuration.
+        This can be passed to the subprocess to ensure it has the same configuration context.
+        """
+        config = AmsdalConfigManager().get_config()
+        return base64.b64encode(config.model_dump_json().encode('utf-8')).decode('utf-8')

amsdal_ml-0.1.1/amsdal_ml/mcp_server/server_retriever_stdio.py

@@ -0,0 +1,59 @@
+import argparse
+import asyncio
+import base64
+import json
+import logging
+import sys
+from typing import Any
+from typing import cast
+
+from amsdal.manager import AmsdalManager
+from amsdal.manager import AsyncAmsdalManager
+from amsdal_utils.config.data_models.amsdal_config import AmsdalConfig
+from amsdal_utils.config.manager import AmsdalConfigManager
+from mcp.server.fastmcp import FastMCP
+
+from amsdal_ml.agents.retriever_tool import retriever_search
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s [%(levelname)s] %(message)s',
+    handlers=[
+        logging.FileHandler("server.log"),
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--amsdal-config", required=False, help="Base64-encoded config string")
+args = parser.parse_args()
+
+logging.info(f"Starting server with args: {args}")
+
+if args.amsdal_config:
+    decoded = base64.b64decode(args.amsdal_config).decode("utf-8")
+    amsdal_config = AmsdalConfig(**json.loads(decoded))
+    logging.info(f"Loaded Amsdal config: {amsdal_config}")
+    AmsdalConfigManager().set_config(amsdal_config)
+
+    manager: Any
+    if amsdal_config.async_mode:
+        manager = AsyncAmsdalManager()
+        logging.info("pre-setup")
+        asyncio.run(cast(Any, manager).setup())
+        logging.info("post-setup")
+        asyncio.run(cast(Any, manager).post_setup())
+        logging.info("manager inited")
+    else:
+        manager = AmsdalManager()
+        cast(Any, manager).setup()
+        cast(Any, manager).post_setup()
+
+server = FastMCP('retriever-stdio')
+server.tool(
+    name='search',
+    description='Semantic search in knowledge base (OpenAI embeddings)',
+    structured_output=True,
+)(retriever_search)
+
+server.run(transport='stdio')

amsdal_ml-0.1.1/amsdal_ml/migrations/0000_initial.py

@@ -0,0 +1,36 @@
+from amsdal_models.migration import migrations
+from amsdal_utils.models.enums import ModuleType
+
+
+class Migration(migrations.Migration):
+    operations: list[migrations.Operation] = [
+        migrations.CreateClass(
+            module_type=ModuleType.CONTRIB,
+            class_name="EmbeddingModel",
+            new_schema={
+                "title": "EmbeddingModel",
+                "required": ["object_class", "object_id", "chunk_index", "raw_text", "embedding"],
+                "properties": {
+                    "object_class": {"type": "string", "title": "Linked object class"},
+                    "object_id": {"type": "string", "title": "Linked object ID"},
+                    "chunk_index": {"type": "integer", "title": "Chunk index"},
+                    "raw_text": {"type": "string", "title": "Raw text used for embedding"},
+                    "embedding": {
+                        "type": "array",
+                        "items": {"type": "number"},
+                        "title": "Embedding",
+                        "additional_type": "vector",
+                        "dimensions": 1536,
+                    },
+                    "tags": {"type": "array", "items": {"type": "string"}, "title": "Embedding tags"},
+                    "ml_metadata": {"type": "anything", "title": "ML metadata"},
+                },
+                "storage_metadata": {
+                    "table_name": "embedding_model",
+                    "db_fields": {},
+                    "primary_key": ["partition_key"],
+                    "foreign_keys": {},
+                },
+            },
+        ),
+    ]

amsdal_ml-0.1.1/amsdal_ml/ml_models/models.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+from collections.abc import AsyncIterator
+
+from amsdal_ml.fileio.base_loader import PLAIN_TEXT
+from amsdal_ml.fileio.base_loader import FileAttachment
+
+
+class ModelError(Exception):
+    """Base exception for all ML models."""
+
+
+class ModelConnectionError(ModelError):
+    """Network or connection failure to the provider (timeouts, DNS, TLS, etc.)."""
+
+
+class ModelRateLimitError(ModelError):
+    """Provider's rate limit reached (HTTP 429)."""
+
+
+class ModelAPIError(ModelError):
+    """API responded with an error (any 4xx/5xx, except 429)."""
+
+
+class MLModel(ABC):
+    @abstractmethod
+    def setup(self) -> None:
+        """Initialize any clients or resources needed before inference."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def teardown(self) -> None:
+        """Clean up resources after use."""
+        raise NotImplementedError
+
+    def supported_attachments(self) -> set[str]:
+        """Return a set of universal attachment kinds, e.g. {PLAIN_TEXT, FILE_ID}."""
+        return {PLAIN_TEXT}
+
+    @abstractmethod
+    def invoke(
+        self,
+        prompt: str,
+        *,
+        attachments: list[FileAttachment] | None = None,
+    ) -> str:
+        """Run synchronous inference with the model."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def ainvoke(
+        self,
+        prompt: str,
+        *,
+        attachments: list[FileAttachment] | None = None,
+    ) -> str:
+        """Run asynchronous inference with the model."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def stream(
+        self,
+        prompt: str,
+        *,
+        attachments: list[FileAttachment] | None = None,
+    ):
+        """Stream synchronous inference results from the model."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def astream(
+        self,
+        prompt: str,
+        *,
+        attachments: list[FileAttachment] | None = None,
+    ) -> AsyncIterator[str]:
+        """
+        Stream asynchronous inference results as an async generator.
+
+        Subclasses should implement this like:
+
+            async def astream(... ) -> AsyncIterator[str]:
+                yield "chunk"
+        """
+        raise NotImplementedError