ailoy-py 0.2.4__cp310-abi3-manylinux_2_28_x86_64.whl

ailoy/__init__.py

@@ -0,0 +1,5 @@
+# ruff: noqa: F401
+# ruff: noqa: I001
+
+from ._core import *  # noqa: F403
+import ailoy._patches

ailoy/_core.pyi

@@ -0,0 +1,918 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+import builtins
+import enum
+import typing
+
+@typing.final
+class Agent:
+    r"""
+    The Agent is the central orchestrator that connects the **language model**, **tools**, and **knowledge** components.
+    It manages the entire reasoning and action loop, coordinating how each subsystem contributes to the final response.
+    
+    In essence, the Agent:
+    
+    - Understands user input
+    - Interprets structured responses from the language model (such as tool calls)
+    - Executes tools as needed
+    - Retrieves and integrates contextual knowledge before or during inference
+    
+    # Public APIs
+    - `run_delta`: Runs a user query and streams incremental deltas (partial outputs)
+    - `run`: Runs a user query and returns a complete message once all deltas are accumulated
+    
+    ## Delta vs. Complete Message
+    A *delta* represents a partial piece of model output, such as a text fragment or intermediate reasoning step.
+    Deltas can be accumulated into a full message using the provided accumulation utilities.
+    This allows real-time streaming while preserving the ability to reconstruct the final structured result.
+    
+    See `MessageDelta`.
+    
+    # Components
+    - **Language Model**: Generates natural language and structured outputs. It interprets the conversation context and predicts the assistant’s next action.
+    - **Tool**: Represents external functions or APIs that the model can dynamically invoke. The `Agent` detects tool calls and automatically executes them during the reasoning loop.
+    - **Knowledge**: Provides retrieval-augmented reasoning by fetching relevant information from stored documents or databases. When available, the `Agent` enriches model input with these results before generating an answer.
+    """
+    @property
+    def lm(self) -> LangModel: ...
+    @property
+    def tools(self) -> builtins.list[Tool]: ...
+    def __new__(cls, lm: LangModel, tools: typing.Optional[typing.Sequence[Tool]] = None, knowledge: typing.Optional[Knowledge] = None) -> Agent: ...
+    def __repr__(self) -> builtins.str: ...
+    def add_tools(self, tools: typing.Sequence[Tool]) -> None: ...
+    def add_tool(self, tool: Tool) -> None: ...
+    def remove_tools(self, tool_names: typing.Sequence[builtins.str]) -> None: ...
+    def remove_tool(self, tool_name: builtins.str) -> None: ...
+    def clear_tools(self) -> None: ...
+    def set_knowledge(self, knowledge: Knowledge) -> None: ...
+    def remove_knowledge(self) -> None: ...
+    def run_delta(self, messages: str | list[Message], config: typing.Optional[AgentConfig] = None) -> MessageDeltaOutputIterator: ...
+    def run_delta_sync(self, messages: str | list[Message], config: typing.Optional[AgentConfig] = None) -> MessageDeltaOutputSyncIterator: ...
+    def run(self, messages: str | list[Message], config: typing.Optional[AgentConfig] = None) -> MessageOutputIterator: ...
+    def run_sync(self, messages: str | list[Message], config: typing.Optional[AgentConfig] = None) -> MessageOutputSyncIterator: ...
+
+@typing.final
+class AgentConfig:
+    r"""
+    Configuration for running the agent.
+    
+    See `LangModelInferConfig` and `KnowledgeConfig` for more details.
+    """
+    @property
+    def inference(self) -> typing.Optional[LangModelInferConfig]: ...
+    @inference.setter
+    def inference(self, value: typing.Optional[LangModelInferConfig]) -> None: ...
+    @property
+    def knowledge(self) -> typing.Optional[KnowledgeConfig]: ...
+    @knowledge.setter
+    def knowledge(self, value: typing.Optional[KnowledgeConfig]) -> None: ...
+    def __new__(cls, inference: typing.Optional[LangModelInferConfig] = None, knowledge: typing.Optional[KnowledgeConfig] = None) -> AgentConfig: ...
+    @classmethod
+    def from_dict(cls, config: dict) -> AgentConfig: ...
+
+@typing.final
+class CacheProgress:
+    @property
+    def comment(self) -> builtins.str: ...
+    @property
+    def current(self) -> builtins.int: ...
+    @property
+    def total(self) -> builtins.int: ...
+    def __repr__(self) -> builtins.str: ...
+
+@typing.final
+class Document:
+    @property
+    def id(self) -> builtins.str: ...
+    @property
+    def title(self) -> typing.Optional[builtins.str]: ...
+    @property
+    def text(self) -> builtins.str: ...
+    def __eq__(self, other: builtins.object) -> builtins.bool: ...
+    def __new__(cls, id: builtins.str, text: builtins.str, title: typing.Optional[builtins.str] = None) -> Document: ...
+
+@typing.final
+class DocumentPolyfill:
+    r"""
+    Provides a polyfill for LLMs that do not natively support the Document feature.
+    """
+    @property
+    def system_message_template(self) -> typing.Optional[builtins.str]: ...
+    @system_message_template.setter
+    def system_message_template(self, value: typing.Optional[builtins.str]) -> None: ...
+    @property
+    def query_message_template(self) -> typing.Optional[builtins.str]: ...
+    @query_message_template.setter
+    def query_message_template(self, value: typing.Optional[builtins.str]) -> None: ...
+    def __new__(cls, system_message_template: typing.Optional[builtins.str] = None, query_message_template: typing.Optional[builtins.str] = None) -> DocumentPolyfill: ...
+    @classmethod
+    def get(cls, kind: typing.Literal["Qwen3"]) -> DocumentPolyfill: ...
+
+@typing.final
+class EmbeddingModel:
+    @classmethod
+    def new_local(cls, model_name: builtins.str, device_id: typing.Optional[builtins.int] = None, validate_checksum: typing.Optional[builtins.bool] = None, progress_callback: typing.Callable[[CacheProgress], None] = None) -> typing.Awaitable[EmbeddingModel]: ...
+    @classmethod
+    def new_local_sync(cls, model_name: builtins.str, device_id: typing.Optional[builtins.int] = None, validate_checksum: typing.Optional[builtins.bool] = None, progress_callback: typing.Callable[[CacheProgress], None] = None) -> EmbeddingModel: ...
+    @classmethod
+    def download(cls, model_name: builtins.str, progress_callback: typing.Callable[[CacheProgress], None] = None) -> None: ...
+    @classmethod
+    def remove(cls, model_name: builtins.str) -> None: ...
+    async def infer(self, text: builtins.str) -> builtins.list[float]: ...
+    def infer_sync(self, text: builtins.str) -> builtins.list[float]: ...
+
+class Grammar:
+    @typing.final
+    class Plain(Grammar):
+        __match_args__ = ()
+        def __new__(cls) -> Grammar.Plain: ...
+    
+    @typing.final
+    class JSON(Grammar):
+        __match_args__ = ()
+        def __new__(cls) -> Grammar.JSON: ...
+    
+    @typing.final
+    class JSONSchema(Grammar):
+        __match_args__ = ("schema",)
+        @property
+        def schema(self) -> builtins.str: ...
+        def __new__(cls, schema: builtins.str) -> Grammar.JSONSchema: ...
+    
+    @typing.final
+    class Regex(Grammar):
+        __match_args__ = ("regex",)
+        @property
+        def regex(self) -> builtins.str: ...
+        def __new__(cls, regex: builtins.str) -> Grammar.Regex: ...
+    
+    @typing.final
+    class CFG(Grammar):
+        __match_args__ = ("cfg",)
+        @property
+        def cfg(self) -> builtins.str: ...
+        def __new__(cls, cfg: builtins.str) -> Grammar.CFG: ...
+    
+    ...
+
+@typing.final
+class KVCacheConfig:
+    @property
+    def context_window_size(self) -> typing.Optional[builtins.int]: ...
+    @context_window_size.setter
+    def context_window_size(self, value: typing.Optional[builtins.int]) -> None: ...
+    @property
+    def prefill_chunk_size(self) -> typing.Optional[builtins.int]: ...
+    @prefill_chunk_size.setter
+    def prefill_chunk_size(self, value: typing.Optional[builtins.int]) -> None: ...
+    @property
+    def sliding_window_size(self) -> typing.Optional[builtins.int]: ...
+    @sliding_window_size.setter
+    def sliding_window_size(self, value: typing.Optional[builtins.int]) -> None: ...
+    def __new__(cls, context_window_size: typing.Optional[builtins.int], prefill_chunk_size: typing.Optional[builtins.int], sliding_window_size: typing.Optional[builtins.int]) -> KVCacheConfig: ...
+
+@typing.final
+class Knowledge:
+    @classmethod
+    def new_vector_store(cls, store: VectorStore, embedding_model: EmbeddingModel) -> Knowledge: ...
+    async def retrieve(self, query: builtins.str, config: KnowledgeConfig) -> builtins.list[Document]: ...
+    def as_tool(self) -> Tool: ...
+
+@typing.final
+class KnowledgeConfig:
+    @property
+    def top_k(self) -> typing.Optional[builtins.int]: ...
+    @top_k.setter
+    def top_k(self, value: typing.Optional[builtins.int]) -> None: ...
+    def __new__(cls, top_k: typing.Optional[builtins.int] = None) -> KnowledgeConfig: ...
+    @classmethod
+    def from_dict(cls, config: dict) -> KnowledgeConfig: ...
+
+@typing.final
+class LangModel:
+    @classmethod
+    def new_local(cls, model_name: builtins.str, device_id: typing.Optional[builtins.int] = None, validate_checksum: typing.Optional[builtins.bool] = None, kv_cache: typing.Optional[KVCacheConfig] = None, progress_callback: typing.Callable[[CacheProgress], None] = None) -> typing.Awaitable[LangModel]: ...
+    @classmethod
+    def new_local_sync(cls, model_name: builtins.str, device_id: typing.Optional[builtins.int] = None, validate_checksum: typing.Optional[builtins.bool] = None, kv_cache: typing.Optional[KVCacheConfig] = None, progress_callback: typing.Callable[[CacheProgress], None] = None) -> LangModel: ...
+    @classmethod
+    def new_stream_api(cls, spec: typing.Literal["ChatCompletion", "OpenAI", "Gemini", "Claude", "Responses", "Grok"], model_name: builtins.str, api_key: builtins.str) -> LangModel: ...
+    @classmethod
+    def download(cls, model_name: builtins.str, progress_callback: typing.Callable[[CacheProgress], None] = None) -> None: ...
+    @classmethod
+    def remove(cls, model_name: builtins.str) -> None: ...
+    def infer_delta(self, messages: str | list[Message], tools: typing.Optional[typing.Sequence[ToolDesc]] = None, documents: typing.Optional[typing.Sequence[Document]] = None, config: typing.Optional[LangModelInferConfig] = None) -> MessageDeltaOutputIterator: ...
+    def infer_delta_sync(self, messages: str | list[Message], tools: typing.Optional[typing.Sequence[ToolDesc]] = None, documents: typing.Optional[typing.Sequence[Document]] = None, config: typing.Optional[LangModelInferConfig] = None) -> MessageDeltaOutputSyncIterator: ...
+    def infer(self, messages: str | list[Message], tools: typing.Optional[typing.Sequence[ToolDesc]] = None, documents: typing.Optional[typing.Sequence[Document]] = None, config: typing.Optional[LangModelInferConfig] = None) -> typing.Awaitable[MessageOutput]: ...
+    def infer_sync(self, messages: str | list[Message], tools: typing.Optional[typing.Sequence[ToolDesc]] = None, documents: typing.Optional[typing.Sequence[Document]] = None, config: typing.Optional[LangModelInferConfig] = None) -> MessageOutput: ...
+    def __repr__(self) -> builtins.str: ...
+
+@typing.final
+class LangModelInferConfig:
+    r"""
+    Configuration parameters that control the behavior of language model inference.
+    
+    # Fields
+    
+    ## `document_polyfill`
+    Configuration describing how retrieved documents are embedded into the model input.
+    If `None`, it does not perform any polyfill, (ignoring documents).
+    
+    ## `think_effort`
+    Controls the model's reasoning intensity.
+    In local models, `low`, `medium`, `high` is ignored.
+    In API models, it is up to it's API. See API parameters.
+    
+    Possible values: `disable`, `enable`, `low`, `medium`, `high`.
+    
+    ## `temperature`
+    Sampling temperature controlling randomness of output.
+    Lower values make output more deterministic; higher values increase diversity.
+    
+    ## `top_p`
+    Nucleus sampling parameter (probability mass cutoff).
+    Limits token sampling to a cumulative probability ≤ `top_p`.`
+    
+    ## `max_tokens`
+    Maximum number of tokens to generate for a single inference.
+    
+    ## `grammar`
+    Optional grammar constraint that restricts valid output forms.  
+    Supported types include:
+    - `Plain`: unconstrained text  
+    - `JSON`: ensures valid JSON output  
+    - `JSONSchema { schema }`: validates JSON against the given schema  
+    - `Regex { regex }`: constrains generation by a regular expression  
+    - `CFG { cfg }`: uses a context-free grammar definition
+    """
+    @property
+    def document_polyfill(self) -> typing.Optional[DocumentPolyfill]: ...
+    @document_polyfill.setter
+    def document_polyfill(self, value: typing.Optional[DocumentPolyfill]) -> None: ...
+    @property
+    def think_effort(self) -> typing.Optional[typing.Literal["disable", "enable", "low", "medium", "high"]]: ...
+    @think_effort.setter
+    def think_effort(self, value: typing.Optional[typing.Literal["disable", "enable", "low", "medium", "high"]]) -> None: ...
+    @property
+    def temperature(self) -> typing.Optional[builtins.float]: ...
+    @temperature.setter
+    def temperature(self, value: typing.Optional[builtins.float]) -> None: ...
+    @property
+    def top_p(self) -> typing.Optional[builtins.float]: ...
+    @top_p.setter
+    def top_p(self, value: typing.Optional[builtins.float]) -> None: ...
+    @property
+    def max_tokens(self) -> typing.Optional[builtins.int]: ...
+    @max_tokens.setter
+    def max_tokens(self, value: typing.Optional[builtins.int]) -> None: ...
+    @property
+    def grammar(self) -> typing.Optional[Grammar]: ...
+    @grammar.setter
+    def grammar(self, value: typing.Optional[Grammar]) -> None: ...
+    def __new__(cls, document_polyfill: typing.Optional[DocumentPolyfill] = None, think_effort: typing.Optional[typing.Literal["disable", "enable", "low", "medium", "high"]] = None, temperature: typing.Optional[builtins.float] = None, top_p: typing.Optional[builtins.float] = None, max_tokens: typing.Optional[builtins.int] = None) -> LangModelInferConfig: ...
+    @classmethod
+    def from_dict(cls, config: dict) -> LangModelInferConfig: ...
+
+@typing.final
+class MCPClient:
+    @property
+    def tools(self) -> builtins.list[Tool]: ...
+    def __repr__(self) -> builtins.str: ...
+    @classmethod
+    def from_stdio(cls, command: builtins.str, args: typing.Sequence[builtins.str]) -> typing.Awaitable[MCPClient]: ...
+    @classmethod
+    def from_streamable_http(cls, url: builtins.str) -> typing.Awaitable[MCPClient]: ...
+    def get_tool(self, name: builtins.str) -> typing.Optional[Tool]: ...
+
+@typing.final
+class Message:
+    r"""
+    A chat message generated by a user, model, or tool.
+    
+    `Message` is the concrete, non-streaming container used by the application to store, transmit, or feed structured content into models or tools.
+    It can represent various kinds of messages, including user input, assistant responses, tool-call outputs, or signed *thinking* metadata.
+    
+    Note that many different kinds of messages can be produced.
+    For example, a language model may internally generate a `thinking` trace before emitting its final output, in order to improve reasoning accuracy.
+    In other cases, a model may produce *function calls* — structured outputs that instruct external tools to perform specific actions.
+    
+    This struct is designed to handle all of these situations in a unified way.
+    
+    # Example
+    
+    ## Rust
+    ```rust
+    let msg = Message::new(Role::User).with_contents([Part::text("hello")]);
+    assert_eq!(msg.role, Role::User);
+    assert_eq!(msg.contents.len(), 1);
+    ```
+    """
+    @property
+    def role(self) -> typing.Literal["system", "user", "assistant", "tool"]:
+        r"""
+        Author of the message.
+        """
+    @role.setter
+    def role(self, value: typing.Literal["system", "user", "assistant", "tool"]) -> None:
+        r"""
+        Author of the message.
+        """
+    @property
+    def contents(self) -> builtins.list[Part]:
+        r"""
+        Primary parts of the message (e.g., text, image, value, or function).
+        """
+    @contents.setter
+    def contents(self, value: typing.Optional[str | list[Part]]) -> None: ...
+    @property
+    def id(self) -> typing.Optional[builtins.str]:
+        r"""
+        Optional stable identifier for deduplication or threading.
+        """
+    @id.setter
+    def id(self, value: typing.Optional[builtins.str]) -> None:
+        r"""
+        Optional stable identifier for deduplication or threading.
+        """
+    @property
+    def thinking(self) -> typing.Optional[builtins.str]:
+        r"""
+        Internal “thinking” text used by some models before producing final output.
+        """
+    @thinking.setter
+    def thinking(self, value: typing.Optional[builtins.str]) -> None:
+        r"""
+        Internal “thinking” text used by some models before producing final output.
+        """
+    @property
+    def tool_calls(self) -> typing.Optional[builtins.list[Part]]:
+        r"""
+        Tool-call parts emitted alongside the main contents.
+        """
+    @tool_calls.setter
+    def tool_calls(self, value: typing.Optional[builtins.list[Part]]) -> None:
+        r"""
+        Tool-call parts emitted alongside the main contents.
+        """
+    @property
+    def signature(self) -> typing.Optional[builtins.str]:
+        r"""
+        Optional signature for the `thinking` field.
+        
+        This is only applicable to certain LLM APIs that require a signature as part of the `thinking` payload.
+        """
+    @signature.setter
+    def signature(self, value: typing.Optional[builtins.str]) -> None:
+        r"""
+        Optional signature for the `thinking` field.
+        
+        This is only applicable to certain LLM APIs that require a signature as part of the `thinking` payload.
+        """
+    def __new__(cls, role: typing.Literal["system", "user", "assistant", "tool"], contents: typing.Optional[str | list[Part]] = None, id: typing.Optional[builtins.str] = None, thinking: typing.Optional[builtins.str] = None, tool_calls: typing.Optional[typing.Sequence[Part]] = None, signature: typing.Optional[builtins.str] = None) -> Message: ...
+    def __repr__(self) -> builtins.str: ...
+    def append_tool_call(self, part: Part) -> None: ...
+
+@typing.final
+class MessageDelta:
+    r"""
+    A streaming, incremental update to a [`Message`].
+    
+    `MessageDelta` accumulates partial outputs (text chunks, tool-call fragments, IDs, signatures, etc.) until they can be materialized as a full [`Message`].
+    It implements [`Delta`] to support accumulation.
+    
+    # Accumulation Rules
+    - `role`: merging two distinct roles fails.
+    - `thinking`: concatenated in arrival order.
+    - `contents`/`tool_calls`: last element is accumulated with the incoming delta when both are compatible (e.g., Text+Text, Function+Function with matching ID policy), otherwise appended as a new fragment.
+    - `id`/`signature`: last-writer-wins.
+    
+    # Finalization
+    - `finish()` converts the accumulated deltas into a fully-formed [`Message`].
+      Fails if required fields (e.g., `role`) are missing or inner deltas cannot be finalized.
+    
+    # Examples
+    ```rust
+    let d1 = MessageDelta::new().with_role(Role::Assistant).with_contents([PartDelta::Text { text: "Hel".into() }]);
+    let d2 = MessageDelta::new().with_contents([PartDelta::Text { text: "lo".into() }]);
+    
+    let merged = d1.accumulate(d2).unwrap();
+    let msg = merged.finish().unwrap();
+    assert_eq!(msg.contents[0].as_text().unwrap(), "Hello");
+    ```
+    """
+    @property
+    def role(self) -> typing.Optional[typing.Literal["system", "user", "assistant", "tool"]]: ...
+    @role.setter
+    def role(self, value: typing.Optional[typing.Literal["system", "user", "assistant", "tool"]]) -> None: ...
+    @property
+    def contents(self) -> builtins.list[PartDelta]: ...
+    @contents.setter
+    def contents(self, value: builtins.list[PartDelta]) -> None: ...
+    @property
+    def id(self) -> typing.Optional[builtins.str]: ...
+    @id.setter
+    def id(self, value: typing.Optional[builtins.str]) -> None: ...
+    @property
+    def thinking(self) -> typing.Optional[builtins.str]: ...
+    @thinking.setter
+    def thinking(self, value: typing.Optional[builtins.str]) -> None: ...
+    @property
+    def tool_calls(self) -> builtins.list[PartDelta]: ...
+    @tool_calls.setter
+    def tool_calls(self, value: builtins.list[PartDelta]) -> None: ...
+    @property
+    def signature(self) -> typing.Optional[builtins.str]: ...
+    @signature.setter
+    def signature(self, value: typing.Optional[builtins.str]) -> None: ...
+    def __new__(cls, role: typing.Optional[typing.Literal["system", "user", "assistant", "tool"]] = None, contents: typing.Optional[typing.Sequence[PartDelta]] = None, id: typing.Optional[builtins.str] = None, thinking: typing.Optional[builtins.str] = None, tool_calls: typing.Optional[typing.Sequence[PartDelta]] = None, signature: typing.Optional[builtins.str] = None) -> MessageDelta: ...
+    def __repr__(self) -> builtins.str: ...
+    def __add__(self, other: MessageDelta) -> MessageDelta: ...
+    def finish(self) -> Message: ...
+
+@typing.final
+class MessageDeltaOutput:
+    r"""
+    A container for a streamed message delta and its termination signal.
+    
+    During streaming, `delta` carries the incremental payload; once a terminal
+    condition is reached, `finish_reason` may be populated to explain why.
+    
+    # Examples
+    ```rust
+    let mut out = MessageOutput::new();
+    out.delta = MessageDelta::new().with_role(Role::Assistant).with_contents([PartDelta::Text { text: "Hi".into() }]);
+    assert!(out.finish_reason.is_none());
+    ```
+    
+    # Lifecycle
+    - While streaming: `finish_reason` is typically `None`.
+    - On completion: `finish_reason` is set; callers can then `finish()` the delta to obtain a concrete [`Message`].
+    """
+    @property
+    def delta(self) -> MessageDelta: ...
+    @delta.setter
+    def delta(self, value: MessageDelta) -> None: ...
+    @property
+    def finish_reason(self) -> typing.Optional[FinishReason]: ...
+    @finish_reason.setter
+    def finish_reason(self, value: typing.Optional[FinishReason]) -> None: ...
+    def __repr__(self) -> builtins.str: ...
+
+@typing.final
+class MessageDeltaOutputIterator:
+    def __aiter__(self) -> MessageDeltaOutputIterator: ...
+    def __anext__(self) -> typing.Awaitable[MessageDeltaOutput]: ...
+
+@typing.final
+class MessageDeltaOutputSyncIterator:
+    def __iter__(self) -> MessageDeltaOutputSyncIterator: ...
+    def __next__(self) -> MessageDeltaOutput: ...
+
+@typing.final
+class MessageOutput:
+    @property
+    def message(self) -> Message: ...
+    @message.setter
+    def message(self, value: Message) -> None: ...
+    @property
+    def finish_reason(self) -> FinishReason: ...
+    @finish_reason.setter
+    def finish_reason(self, value: FinishReason) -> None: ...
+    def __repr__(self) -> builtins.str: ...
+
+@typing.final
+class MessageOutputIterator:
+    def __aiter__(self) -> MessageOutputIterator: ...
+    def __anext__(self) -> typing.Awaitable[MessageOutput]: ...
+
+@typing.final
+class MessageOutputSyncIterator:
+    def __iter__(self) -> MessageOutputSyncIterator: ...
+    def __next__(self) -> MessageOutput: ...
+
+class Part:
+    r"""
+    Represents a semantically meaningful content unit exchanged between the model and the user.
+    
+    Conceptually, each `Part` encapsulates a piece of **data** that contributes
+    to a chat message — such as text, a function invocation, or an image.  
+    
+    For example, a single message consisting of a sequence like  
+    `(text..., image, text...)` is represented as a `Message` containing
+    an array of three `Part` elements.
+    
+    Note that a `Part` does **not** carry "intent", such as "reasoning" or "tool call".
+    These higher-level semantics are determined by the context of a [`Message`].
+    
+    # Example
+    
+    ## Rust
+    ```rust
+    let part = Part::text("Hello, world!");
+    assert!(part.is_text());
+    ```
+    """
+    @property
+    def part_type(self) -> builtins.str: ...
+    def __repr__(self) -> builtins.str: ...
+    @classmethod
+    def image_from_bytes(cls, data: bytes) -> Part: ...
+    @classmethod
+    def image_from_base64(cls, data: builtins.str) -> Part: ...
+    @classmethod
+    def image_from_url(cls, url: builtins.str) -> Part: ...
+    @typing.final
+    class Text(Part):
+        r"""
+        Plain utf-8 encoded text.
+        """
+        __match_args__ = ("text",)
+        @property
+        def text(self) -> builtins.str: ...
+        def __new__(cls, text: builtins.str) -> Part.Text: ...
+    
+    @typing.final
+    class Function(Part):
+        r"""
+        Represents a structured function call to an external tool.
+        
+        Many language models (LLMs) use a **function calling** mechanism to extend their capabilities.
+        When an LLM decides to use external *tools*, it produces a structured output called a `function`.
+        A function conventionally consists of two fields: a `name`, and an `arguments` field formatted as JSON.
+        This is conceptually similar to making an HTTP POST request, where the request body carries a single JSON object.
+        
+        This struct models that convention, representing a function invocation request
+        from an LLM to an external tool or API.
+        
+        # Examples
+        ```rust
+        let f = PartFunction {
+            name: "translate".to_string(),
+            arguments: Value::from_json(r#"{"source": "hello", "lang": "cn"}"#).unwrap(),
+        };
+        ```
+        """
+        __match_args__ = ("id", "function",)
+        @property
+        def id(self) -> typing.Optional[builtins.str]: ...
+        @property
+        def function(self) -> PartFunction: ...
+        def __new__(cls, id: typing.Optional[builtins.str], function: PartFunction) -> Part.Function: ...
+    
+    @typing.final
+    class Value(Part):
+        r"""
+        Holds a structured data value, typically considered as a JSON structure.
+        """
+        __match_args__ = ("value",)
+        @property
+        def value(self) -> typing.Any: ...
+        def __new__(cls, value: typing.Any) -> Part.Value: ...
+    
+    @typing.final
+    class Image(Part):
+        r"""
+        Contains an image payload or reference used within a message part.
+        The image may be provided as raw binary data or an encoded format (e.g., PNG, JPEG),
+        or as a reference via a URL. Optional metadata can be included alongside the image.
+        """
+        __match_args__ = ("image",)
+        @property
+        def image(self) -> PartImage: ...
+        def __new__(cls, image: PartImage) -> Part.Image: ...
+    
+
+class PartDelta:
+    r"""
+    Represents a partial or incremental update (delta) of a [`Part`].
+    
+    This type enables composable, streaming updates to message parts.
+    For example, text may be produced token-by-token, or a function call
+    may be emitted gradually as its arguments stream in.
+    
+    # Example
+    
+    ## Rust
+    ```rust
+    let d1 = PartDelta::Text { text: "Hel".into() };
+    let d2 = PartDelta::Text { text: "lo".into() };
+    let merged = d1.accumulate(d2).unwrap();
+    assert_eq!(merged.to_text().unwrap(), "Hello");
+    ```
+    
+    # Error Handling
+    Accumulation or finalization may return an error if incompatible deltas
+    (e.g. mismatched function IDs) are combined or invalid JSON arguments are given.
+    """
+    @property
+    def part_type(self) -> builtins.str: ...
+    def __repr__(self) -> builtins.str: ...
+    @typing.final
+    class Text(PartDelta):
+        r"""
+        Incremental text fragment.
+        """
+        __match_args__ = ("text",)
+        @property
+        def text(self) -> builtins.str: ...
+        def __new__(cls, text: builtins.str) -> PartDelta.Text: ...
+    
+    @typing.final
+    class Function(PartDelta):
+        r"""
+        Incremental function call fragment.
+        """
+        __match_args__ = ("id", "function",)
+        @property
+        def id(self) -> typing.Optional[builtins.str]: ...
+        @property
+        def function(self) -> PartDeltaFunction: ...
+        def __new__(cls, id: typing.Optional[builtins.str], function: PartDeltaFunction) -> PartDelta.Function: ...
+    
+    @typing.final
+    class Value(PartDelta):
+        r"""
+        JSON-like value update.
+        """
+        __match_args__ = ("value",)
+        @property
+        def value(self) -> typing.Any: ...
+        def __new__(cls, value: typing.Any) -> PartDelta.Value: ...
+    
+    @typing.final
+    class Null(PartDelta):
+        r"""
+        Placeholder representing no data yet.
+        """
+        __match_args__ = ()
+        def __new__(cls) -> PartDelta.Null: ...
+    
+
+class PartDeltaFunction:
+    r"""
+    Represents an incremental update (delta) of a function part.
+    
+    This type is used during streaming or partial message generation, when function calls are being streamed as text chunks or partial JSON fragments.
+    
+    # Variants
+    * `Verbatim(String)` — Raw text content, typically a partial JSON fragment.
+    * `WithStringArgs { name, arguments }` — Function name and its serialized arguments as strings.
+    * `WithParsedArgs { name, arguments }` — Function name and parsed arguments as a `Value`.
+    
+    # Use Case
+    When the model streams out a function call response (e.g., `"function_call":{"name":...}`),
+    the incremental deltas can be accumulated until the full function payload is formed.
+    
+    # Example
+    ```rust
+    let delta = PartDeltaFunction::WithStringArgs {
+        name: "translate".into(),
+        arguments: r#"{"text":"hi"}"#.into(),
+    };
+    ```
+    """
+    @typing.final
+    class Verbatim(PartDeltaFunction):
+        __match_args__ = ("text",)
+        @property
+        def text(self) -> builtins.str: ...
+        def __new__(cls, text: builtins.str) -> PartDeltaFunction.Verbatim: ...
+    
+    @typing.final
+    class WithStringArgs(PartDeltaFunction):
+        __match_args__ = ("name", "arguments",)
+        @property
+        def name(self) -> builtins.str: ...
+        @property
+        def arguments(self) -> builtins.str: ...
+        def __new__(cls, name: builtins.str, arguments: builtins.str) -> PartDeltaFunction.WithStringArgs: ...
+    
+    @typing.final
+    class WithParsedArgs(PartDeltaFunction):
+        __match_args__ = ("name", "arguments",)
+        @property
+        def name(self) -> builtins.str: ...
+        @property
+        def arguments(self) -> typing.Any: ...
+        def __new__(cls, name: builtins.str, arguments: typing.Any) -> PartDeltaFunction.WithParsedArgs: ...
+    
+    ...
+
+@typing.final
+class PartFunction:
+    r"""
+    Represents a function call contained within a message part.
+    """
+    @property
+    def name(self) -> builtins.str: ...
+    @property
+    def arguments(self) -> dict[str, typing.Any]: ...
+    def __eq__(self, other: builtins.object) -> builtins.bool: ...
+    def __new__(cls, name: builtins.str, arguments: typing.Any) -> PartFunction: ...
+    def __repr__(self) -> builtins.str: ...
+
+class PartImage:
+    r"""
+    Represents the image data contained in a [`Part`].
+    
+    `PartImage` provides structured access to image data.
+    Currently, it only implments "binary" types.
+    
+    # Example
+    ```rust
+    let part = Part::image_binary(640, 480, "rgb", (0..640*480*3).map(|i| (i % 255) as u8)).unwrap();
+    
+    if let Some(img) = part.as_image() {
+        assert_eq!(img.height(), 640);
+        assert_eq!(img.width(), 480);
+    }
+    ```
+    """
+    @typing.final
+    class Binary(PartImage):
+        __match_args__ = ("height", "width", "colorspace", "data",)
+        @property
+        def height(self) -> builtins.int: ...
+        @property
+        def width(self) -> builtins.int: ...
+        @property
+        def colorspace(self) -> typing.Literal["grayscale", "rgb", "rgba"]: ...
+        @property
+        def data(self) -> typing.Any: ...
+        def __new__(cls, height: builtins.int, width: builtins.int, colorspace: typing.Literal["grayscale", "rgb", "rgba"], data: typing.Any) -> PartImage.Binary: ...
+    
+    @typing.final
+    class Url(PartImage):
+        __match_args__ = ("url",)
+        @property
+        def url(self) -> builtins.str: ...
+        def __new__(cls, url: builtins.str) -> PartImage.Url: ...
+    
+    ...
+
+class Tool:
+    @classmethod
+    def new_builtin(cls, kind: typing.Literal["terminal", "web_search_duckduckgo", "web_fetch"], **kwargs: typing.Any) -> Tool: ...
+    @classmethod
+    def new_py_function(cls, func: typing.Any, desc: typing.Optional[ToolDesc] = None) -> Tool: ...
+    def __repr__(self) -> builtins.str: ...
+    def get_description(self) -> ToolDesc: ...
+    def __call__(self, **kwargs: typing.Any) -> typing.Awaitable[typing.Any]: ...
+    def call(self, **kwargs: typing.Any) -> typing.Awaitable[typing.Any]: ...
+    def call_sync(self, **kwargs: typing.Any) -> typing.Any: ...
+
+@typing.final
+class ToolDesc:
+    r"""
+    Describes a **tool** (or function) that a language model can invoke.
+    
+    `ToolDesc` defines the schema, behavior, and input/output specification of a callable
+    external function, allowing an LLM to understand how to use it.
+    
+    The primary role of this struct is to describe to the LLM what a *tool* does,
+    how it can be invoked, and what input (`parameters`) and output (`returns`) schemas it expects.
+    
+    The format follows the same **schema conventions** used by Hugging Face’s
+    `transformers` library, as well as APIs such as *OpenAI* and *Anthropic*.
+    The `parameters` and `returns` fields are typically defined using **JSON Schema**.
+    
+    We provide a builder [`ToolDescBuilder`] helper for convenient and fluent construction.
+    Please refer to [`ToolDescBuilder`].
+    
+    # Example
+    ```rust
+    use crate::value::{ToolDescBuilder, to_value};
+    
+    let desc = ToolDescBuilder::new("temperature")
+        .description("Get the current temperature for a given city")
+        .parameters(to_value!({
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "description": "The city name"
+                },
+                "unit": {
+                    "type": "string",
+                    "description": "Temperature unit (default: Celsius)",
+                    "enum": ["Celsius", "Fahrenheit"]
+                }
+            },
+            "required": ["location"]
+        }))
+        .returns(to_value!({
+            "type": "number"
+        }))
+        .build();
+    
+    assert_eq!(desc.name, "temperature");
+    ```
+    """
+    @property
+    def name(self) -> builtins.str: ...
+    @property
+    def description(self) -> typing.Optional[builtins.str]: ...
+    @property
+    def parameters(self) -> dict: ...
+    @property
+    def returns(self) -> typing.Optional[dict]: ...
+    def __new__(cls, name: builtins.str, description: typing.Optional[builtins.str], parameters: dict, *, returns: typing.Optional[dict] = None) -> ToolDesc: ...
+    def __repr__(self) -> builtins.str: ...
+
+@typing.final
+class VectorStore:
+    @classmethod
+    def new_faiss(cls, dim: builtins.int) -> VectorStore: ...
+    @classmethod
+    def new_chroma(cls, url: builtins.str, collection_name: typing.Optional[builtins.str]) -> VectorStore: ...
+    def add_vector(self, input: VectorStoreAddInput) -> builtins.str: ...
+    def add_vectors(self, inputs: typing.Sequence[VectorStoreAddInput]) -> builtins.list[builtins.str]: ...
+    def get_by_id(self, id: builtins.str) -> typing.Optional[VectorStoreGetResult]: ...
+    def get_by_ids(self, ids: typing.Sequence[builtins.str]) -> builtins.list[VectorStoreGetResult]: ...
+    def retrieve(self, query_embedding: builtins.list[float], top_k: builtins.int) -> builtins.list[VectorStoreRetrieveResult]: ...
+    def batch_retrieve(self, query_embeddings: typing.Sequence[builtins.list[float]], top_k: builtins.int) -> builtins.list[builtins.list[VectorStoreRetrieveResult]]: ...
+    def remove_vector(self, id: builtins.str) -> None: ...
+    def remove_vectors(self, ids: typing.Sequence[builtins.str]) -> None: ...
+    def clear(self) -> None: ...
+    def count(self) -> builtins.int: ...
+
+@typing.final
+class VectorStoreAddInput:
+    @property
+    def embedding(self) -> builtins.list[float]: ...
+    @embedding.setter
+    def embedding(self, value: builtins.list[float]) -> None: ...
+    @property
+    def document(self) -> builtins.str: ...
+    @document.setter
+    def document(self, value: builtins.str) -> None: ...
+    @property
+    def metadata(self) -> typing.Optional[builtins.dict[builtins.str, typing.Any]]: ...
+    @metadata.setter
+    def metadata(self, value: typing.Optional[builtins.dict[builtins.str, typing.Any]]) -> None: ...
+    def __new__(cls, embedding: builtins.list[float], document: builtins.str, metadata: typing.Optional[typing.Mapping[builtins.str, typing.Any]] = None) -> VectorStoreAddInput: ...
+
+@typing.final
+class VectorStoreGetResult:
+    @property
+    def id(self) -> builtins.str: ...
+    @id.setter
+    def id(self, value: builtins.str) -> None: ...
+    @property
+    def document(self) -> builtins.str: ...
+    @document.setter
+    def document(self, value: builtins.str) -> None: ...
+    @property
+    def metadata(self) -> typing.Optional[builtins.dict[builtins.str, typing.Any]]: ...
+    @metadata.setter
+    def metadata(self, value: typing.Optional[builtins.dict[builtins.str, typing.Any]]) -> None: ...
+    @property
+    def embedding(self) -> builtins.list[float]: ...
+    @embedding.setter
+    def embedding(self, value: builtins.list[float]) -> None: ...
+
+@typing.final
+class VectorStoreRetrieveResult:
+    @property
+    def id(self) -> builtins.str: ...
+    @id.setter
+    def id(self, value: builtins.str) -> None: ...
+    @property
+    def document(self) -> builtins.str: ...
+    @document.setter
+    def document(self, value: builtins.str) -> None: ...
+    @property
+    def metadata(self) -> typing.Optional[builtins.dict[builtins.str, typing.Any]]: ...
+    @metadata.setter
+    def metadata(self, value: typing.Optional[builtins.dict[builtins.str, typing.Any]]) -> None: ...
+    @property
+    def distance(self) -> builtins.float: ...
+    @distance.setter
+    def distance(self, value: builtins.float) -> None: ...
+
+@typing.final
+class FinishReason(enum.Enum):
+    r"""
+    Explains why a language model's streamed generation finished.
+    """
+    Stop = ...
+    r"""
+    The model stopped naturally (e.g., EOS token or stop sequence).
+    """
+    Length = ...
+    r"""
+    Hit the maximum token/length limit.
+    """
+    ToolCall = ...
+    r"""
+    Stopped because a tool call was produced, waiting for it's execution.
+    """
+    Refusal = ...
+    r"""
+    Content was refused/filtered; string provides reason.
+    """
+
+    def __repr__(self) -> builtins.str: ...
+
+def ailoy_model_cli() -> None: ...
+

ailoy/_patches.py

@@ -0,0 +1,256 @@
+import inspect
+import json
+import re
+import types
+from typing import (
+    Any,
+    Callable,
+    Literal,
+    Optional,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from ailoy._core import Tool, ToolDesc
+
+description_re = re.compile(r"^(.*?)[\n\s]*(Args:|Returns:|Raises:|\Z)", re.DOTALL)
+# Extracts the Args: block from the docstring
+args_re = re.compile(r"\n\s*Args:\n\s*(.*?)[\n\s]*(Returns:|Raises:|\Z)", re.DOTALL)
+# Splits the Args: block into individual arguments
+args_split_re = re.compile(
+    r"""
+(?:^|\n)  # Match the start of the args block, or a newline
+\s*(\w+):\s*  # Capture the argument name and strip spacing
+(.*?)\s*  # Capture the argument description, which can span multiple lines, and strip trailing spacing
+(?=\n\s*\w+:|\Z)  # Stop when you hit the next argument or the end of the block
+""",
+    re.DOTALL | re.VERBOSE,
+)
+# Extracts the Returns: block from the docstring, if present. Note that most chat templates ignore the return type/doc!
+returns_re = re.compile(r"\n\s*Returns:\n\s*(.*?)[\n\s]*(Raises:|\Z)", re.DOTALL)
+
+
+class TypeHintParsingException(Exception):
+    """Exception raised for errors in parsing type hints to generate JSON schemas"""
+
+    pass
+
+
+class DocstringParsingException(Exception):
+    """Exception raised for errors in parsing docstrings to generate JSON schemas"""
+
+    pass
+
+
+def _get_json_schema_type(param_type: type) -> dict[str, str]:
+    type_mapping = {
+        int: {"type": "integer"},
+        float: {"type": "number"},
+        str: {"type": "string"},
+        bool: {"type": "boolean"},
+        type(None): {"type": "null"},
+        Any: {},
+    }
+    # if is_vision_available():
+    #     type_mapping[Image] = {"type": "image"}
+    # if is_torch_available():
+    #     type_mapping[Tensor] = {"type": "audio"}
+    return type_mapping.get(param_type, {"type": "object"})
+
+
+def _parse_type_hint(hint: str) -> dict:
+    origin = get_origin(hint)
+    args = get_args(hint)
+
+    if origin is None:
+        try:
+            return _get_json_schema_type(hint)
+        except KeyError:
+            raise TypeHintParsingException(
+                "Couldn't parse this type hint, likely due to a custom class or object: ",
+                hint,
+            )
+
+    elif origin is Union or (hasattr(types, "UnionType") and origin is types.UnionType):
+        # Recurse into each of the subtypes in the Union, except None, which is handled separately at the end
+        subtypes = [_parse_type_hint(t) for t in args if t is not type(None)]
+        if len(subtypes) == 1:
+            # A single non-null type can be expressed directly
+            return_dict = subtypes[0]
+        elif all(isinstance(subtype["type"], str) for subtype in subtypes):
+            # A union of basic types can be expressed as a list in the schema
+            return_dict = {"type": sorted([subtype["type"] for subtype in subtypes])}
+        else:
+            # A union of more complex types requires "anyOf"
+            return_dict = {"anyOf": subtypes}
+        if type(None) in args:
+            return_dict["nullable"] = True
+        return return_dict
+
+    elif origin is Literal and len(args) > 0:
+        LITERAL_TYPES = (int, float, str, bool, type(None))
+        args_types = []
+        for arg in args:
+            if type(arg) not in LITERAL_TYPES:
+                raise TypeHintParsingException(
+                    "Only the valid python literals can be listed in typing.Literal."
+                )
+            arg_type = _get_json_schema_type(type(arg)).get("type")
+            if arg_type is not None and arg_type not in args_types:
+                args_types.append(arg_type)
+        return {
+            "type": args_types.pop() if len(args_types) == 1 else list(args_types),
+            "enum": list(args),
+        }
+
+    elif origin is list:
+        if not args:
+            return {"type": "array"}
+        else:
+            # Lists can only have a single type argument, so recurse into it
+            return {"type": "array", "items": _parse_type_hint(args[0])}
+
+    elif origin is tuple:
+        if not args:
+            return {"type": "array"}
+        if len(args) == 1:
+            raise TypeHintParsingException(
+                f"The type hint {str(hint).replace('typing.', '')} is a Tuple with a single element, which "
+                "we do not automatically convert to JSON schema as it is rarely necessary. If this input can contain "
+                "more than one element, we recommend "
+                "using a list[] type instead, or if it really is a single element, remove the tuple[] wrapper and just "
+                "pass the element directly."
+            )
+        if ... in args:
+            raise TypeHintParsingException(
+                "Conversion of '...' is not supported in Tuple type hints. "
+                "Use list[] types for variable-length"
+                " inputs instead."
+            )
+        return {"type": "array", "prefixItems": [_parse_type_hint(t) for t in args]}
+
+    elif origin is dict:
+        # The JSON equivalent to a dict is 'object', which mandates that all keys are strings
+        # However, we can specify the type of the dict values with "additionalProperties"
+        out = {"type": "object"}
+        if len(args) == 2:
+            out["additionalProperties"] = _parse_type_hint(args[1])
+        return out
+
+    raise TypeHintParsingException(
+        "Couldn't parse this type hint, likely due to a custom class or object: ", hint
+    )
+
+
+def _convert_type_hints_to_json_schema(func: Callable) -> dict:
+    type_hints = get_type_hints(func)
+    signature = inspect.signature(func)
+    required = []
+    for param_name, param in signature.parameters.items():
+        if param.annotation == inspect.Parameter.empty:
+            raise TypeHintParsingException(
+                f"Argument {param.name} is missing a type hint in function {func.__name__}"
+            )
+        if param.default == inspect.Parameter.empty:
+            required.append(param_name)
+
+    properties = {}
+    for param_name, param_type in type_hints.items():
+        properties[param_name] = _parse_type_hint(param_type)
+
+    schema = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+
+    return schema
+
+
+def parse_google_format_docstring(
+    docstring: str,
+) -> tuple[Optional[str], Optional[dict], Optional[str]]:
+    """
+    Parses a Google-style docstring to extract the function description,
+    argument descriptions, and return description.
+
+    Args:
+        docstring (str): The docstring to parse.
+
+    Returns:
+        The function description, arguments, and return description.
+    """
+
+    # Extract the sections
+    description_match = description_re.search(docstring)
+    args_match = args_re.search(docstring)
+    returns_match = returns_re.search(docstring)
+
+    # Clean and store the sections
+    description = description_match.group(1).strip() if description_match else None
+    docstring_args = args_match.group(1).strip() if args_match else None
+    returns = returns_match.group(1).strip() if returns_match else None
+
+    # Parsing the arguments into a dictionary
+    if docstring_args is not None:
+        docstring_args = "\n".join(
+            [line for line in docstring_args.split("\n") if line.strip()]
+        )  # Remove blank lines
+        matches = args_split_re.findall(docstring_args)
+        args_dict = {
+            match[0]: re.sub(r"\s*\n+\s*", " ", match[1].strip()) for match in matches
+        }
+    else:
+        args_dict = {}
+
+    return description, args_dict, returns
+
+
+def get_json_schema(func: Callable) -> dict:
+    doc = inspect.getdoc(func)
+    if not doc:
+        raise DocstringParsingException(
+            f"Cannot generate JSON schema for {func.__name__} because it has no docstring!"
+        )
+    doc = doc.strip()
+    main_doc, param_descriptions, return_doc = parse_google_format_docstring(doc)
+
+    json_schema = _convert_type_hints_to_json_schema(func)
+    if (return_dict := json_schema["properties"].pop("return", None)) is not None:
+        if (
+            return_doc is not None
+        ):  # We allow a missing return docstring since most templates ignore it
+            return_dict["description"] = return_doc
+    for arg, schema in json_schema["properties"].items():
+        if arg not in param_descriptions:
+            raise DocstringParsingException(
+                f"Cannot generate JSON schema for {func.__name__} because the docstring has no description for the argument '{arg}'"
+            )
+        desc = param_descriptions[arg]
+        enum_choices = re.search(r"\(choices:\s*(.*?)\)\s*$", desc, flags=re.IGNORECASE)
+        if enum_choices:
+            schema["enum"] = [c.strip() for c in json.loads(enum_choices.group(1))]
+            desc = enum_choices.string[: enum_choices.start()].strip()
+        schema["description"] = desc
+
+    output = {"name": func.__name__, "description": main_doc, "parameters": json_schema}
+    if return_dict is not None:
+        output["returns"] = return_dict
+    return {"type": "function", "function": output}
+
+
+def new_py_function(
+    cls: Tool, func: Callable, tool_desc: Optional[ToolDesc] = None
+) -> Tool:
+    if tool_desc is None:
+        try:
+            json_schema = get_json_schema(func)
+        except (TypeHintParsingException, DocstringParsingException) as e:
+            raise ValueError("Failed to parse docstring", e)
+
+        tool_desc = ToolDesc(**json_schema.get("function"))
+
+    return cls.__new_py_function__(tool_desc, func)
+
+
+setattr(Tool, "new_py_function", classmethod(new_py_function))

ailoy_py-0.2.4.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: ailoy-py
+Version: 0.2.4
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Summary: A lightweight library for building AI applications
+Author-email: "Brekkylab Inc." <contact@brekkylab.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://brekkylab.github.io/ailoy
+Project-URL: Homepage, https://brekkylab.github.io/ailoy
+Project-URL: Issues, https://github.com/brekkylab/ailoy/issues
+Project-URL: Repository, https://github.com/brekkylab/ailoy
+
+# ailoy-py
+
+Ailoy is a lightweight library for building AI applications — such as **agent systems** or **RAG pipelines** — with ease. It is designed to enable AI features effortlessly, one can just import and use.
+
+See our [documentation](https://brekkylab.github.io/ailoy) for more details.
+
+## Install
+
+```bash
+pip install ailoy-py
+```
+
+## Quickstart
+
+### Asynchronous version (recommended)
+```python
+import asyncio
+
+import ailoy as ai
+
+
+async def main():
+    # Create Qwen3-0.6B local LangModel
+    model = await ai.LangModel.new_local("Qwen/Qwen3-0.6B")
+
+    # Create an agent using this model
+    agent = ai.Agent(model)
+
+    # Ask a prompt and iterate over agent's responses
+    async for resp in agent.run("What is your name?"):
+        print(resp)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Synchronous version
+```python
+import ailoy as ai
+
+
+def main():
+    # Create Qwen3-0.6B LocalLanguageModel
+    model = ai.LangModel.new_local_sync("Qwen/Qwen3-0.6B")
+
+    # Create an agent using this model
+    agent = ai.Agent(model)
+
+    # Ask a prompt and iterate over agent's responses
+    for resp in agent.run_sync("What is your name?"):
+        print(resp)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## Building from source
+
+### Prerequisites
+
+- Rust >= 1.88
+- Python >= 3.10
+- C/C++ compiler
+  (recommended versions are below)
+  - GCC >= 13
+  - LLVM Clang >= 17
+  - Apple Clang >= 15
+  - MSVC >= 19.29
+- CMake >= 3.28.0
+- Git
+- OpenMP (required to build Faiss)
+- BLAS (required to build Faiss)
+- LAPACK (required to build Faiss)
+- Vulkan SDK (on Windows and Linux)
+
+> [!WARNING]
+> To build binding, you must change the crate type to **`cdylib`** in [Cargo.toml](../../Cargo.toml).
+>
+> ```toml
+> [lib]
+> crate-type = ["dylib"] # <- Change this to ["cdylib"]
+> ```
+
+
+### Setup development environment
+
+```bash
+pip install maturin
+
+# This generates `_core.cpython-3xx-darwin.so` under `ailoy/`
+maturin develop
+```
+
+### Generate wheel
+
+```bash
+maturin build --out ./dist
+```
+

ailoy_py-0.2.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+ailoy/__init__.py,sha256=gjSajwEPDaWJAXvM744fj_wXHYrpRLR38sYWj_xUp-k,96
+ailoy/_core.abi3.so,sha256=wVzbAwMfXsiuURQ8lQfGNFg3D-vBlEmPUwLua0n_EnA,34447561
+ailoy/_core.pyi,sha256=HTPWsidoLyoLH2jBjlg7vt-23biqRXMKhqBtMQnUz30,38704
+ailoy/_patches.py,sha256=bJg-jl64VKWbFbLyxqM-ZY3a3CK8RoNGzMF6CpWU2pI,9602
+ailoy_py.libs/libfaiss-b004fceb.so,sha256=e02JSyUH4KERET9e1rNexUbZSWyImWkKCk7ZN8t4ymg,11257937
+ailoy_py.libs/libgomp-e985bcbb.so.1.0.0,sha256=pDkE5PopcwHUZA3BuzyKNIC0BvmeSY66mxkUtoqrYEo,253289
+ailoy_py.libs/libtvm_ffi-9e4a703d.so,sha256=exaT3IeM7GD5KXIRSUMlb53-6AQlYklHAZuuZefcNhk,1135113
+ailoy_py.libs/libtvm_runtime-b87d417d.so,sha256=CPsHFl8zASSjgwfPAalBv8WkDwhMP2A4xfCaieO9ndI,5927721
+ailoy_py-0.2.4.dist-info/METADATA,sha256=IyNWRcnuFmfYOD1Tghlv5buoNz-TYgPTRz9StoirpYI,3183
+ailoy_py-0.2.4.dist-info/WHEEL,sha256=IFJVkQ8769pcslF3jPXXkSmy4yVHIAHaSOV_0yFIexE,109
+ailoy_py-0.2.4.dist-info/entry_points.txt,sha256=2QfqZEtN7J34DEJaPEf_zmQalbrI3NMDGJT81mdgXjQ,58
+ailoy_py-0.2.4.dist-info/RECORD,,
+ailoy_py-0.2.4.dist-info/sboms/auditwheel.cdx.json,sha256=7d965nwURfbckBSej25GURuVgxaimx51zflOxOd_qPg,1315

ailoy_py-0.2.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.2)
+Root-Is-Purelib: false
+Tag: cp310-abi3-manylinux_2_28_x86_64
+

ailoy_py-0.2.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ailoy-model=ailoy._core:ailoy_model_cli

ailoy_py-0.2.4.dist-info/sboms/auditwheel.cdx.json

@@ -0,0 +1 @@
+{"bomFormat": "CycloneDX", "specVersion": "1.4", "version": 1, "metadata": {"component": {"type": "library", "bom-ref": "pkg:pypi/ailoy_py@0.2.4?file_name=ailoy_py-0.2.4-cp310-abi3-manylinux_2_28_x86_64.whl", "name": "ailoy_py", "version": "0.2.4", "purl": "pkg:pypi/ailoy_py@0.2.4?file_name=ailoy_py-0.2.4-cp310-abi3-manylinux_2_28_x86_64.whl"}, "tools": [{"name": "auditwheel", "version": "6.5.0"}]}, "components": [{"type": "library", "bom-ref": "pkg:pypi/ailoy_py@0.2.4?file_name=ailoy_py-0.2.4-cp310-abi3-manylinux_2_28_x86_64.whl", "name": "ailoy_py", "version": "0.2.4", "purl": "pkg:pypi/ailoy_py@0.2.4?file_name=ailoy_py-0.2.4-cp310-abi3-manylinux_2_28_x86_64.whl"}, {"type": "library", "bom-ref": "pkg:rpm/almalinux/libgomp@8.5.0-28.el8_10.alma.1#c61017c9a24eb6e1e1a3cdc9becd004a6419cbda3d54b4848b98f240a4829571", "name": "libgomp", "version": "8.5.0-28.el8_10.alma.1", "purl": "pkg:rpm/almalinux/libgomp@8.5.0-28.el8_10.alma.1"}], "dependencies": [{"ref": "pkg:pypi/ailoy_py@0.2.4?file_name=ailoy_py-0.2.4-cp310-abi3-manylinux_2_28_x86_64.whl", "dependsOn": ["pkg:rpm/almalinux/libgomp@8.5.0-28.el8_10.alma.1#c61017c9a24eb6e1e1a3cdc9becd004a6419cbda3d54b4848b98f240a4829571"]}, {"ref": "pkg:rpm/almalinux/libgomp@8.5.0-28.el8_10.alma.1#c61017c9a24eb6e1e1a3cdc9becd004a6419cbda3d54b4848b98f240a4829571"}]}