py-ai-toolkit 0.2.0__tar.gz

py_ai_toolkit-0.2.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Paulo Mattos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_ai_toolkit-0.2.0/MANIFEST.in

@@ -0,0 +1,38 @@
+# Include the essential files
+include LICENSE.txt
+include README.md
+include requirements.txt
+include setup.py
+
+# Include all Python files in the main directories
+recursive-include ait *.py
+recursive-include tests *.py
+
+# Exclude unnecessary directories and files
+exclude .github/*
+exclude .gitignore
+exclude .vscode/*
+exclude .venv/*
+exclude .pytest_cache/*
+recursive-exclude ait/__pycache__ *
+recursive-exclude tests/__pycache__ *
+# Include the essential files
+include LICENSE.txt
+include readme.md
+include requirements.txt
+include setup.py
+
+# Include all Python files in the main directories
+recursive-include ait *.py
+recursive-include tests *.py
+
+# Exclude unnecessary directories and files
+exclude .gitignore
+exclude .vscode/*
+exclude .venv/*
+exclude .pytest_cache/*
+exclude push-all.sh
+exclude ait.egg-info/*
+recursive-exclude ait/__pycache__ *
+recursive-exclude tests/__pycache__ *
+recursive-exclude ait.egg-info *

py_ai_toolkit-0.2.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: py-ai-toolkit
+Version: 0.2.0
+Summary: A set of tools for easily interacting with LLMs.
+Author-email: "@paulomtts" <paulomtts@outlook.com>
+License: MIT
+Project-URL: Homepage, https://github.com/paulomtts/Grafo-AI-Tools.git
+Keywords: ai,agents,llm,workflows
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: build>=1.3.0
+Requires-Dist: bump2version>=1.0.1
+Requires-Dist: grafo>=0.2.36
+Requires-Dist: instructor>=1.13.0
+Requires-Dist: openai>=1.104.2
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: pytest>=8.4.1
+Requires-Dist: pytest-asyncio>=1.1.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: toon-python>=0.1.2
+Dynamic: license-file
+
+# Install
+```
+uv add py-ai-toolkit
+```
+
+# WHAT
+A set of tools for easily interacting with LLMs.
+
+# WHY
+Building AI-driven software leans upon a number of utilities, such as prompt building and LLM calling via HTTP requests. Additionally, writing agents and workflows can prove particularly challenging using conventional code structures.
+
+# HOW
+This simple library offers a set of predefined functions for:
+- Easy prompting - you need only provide a path
+- Calling LLMs - instructor takes care of that for us
+- Modifying response models - we use Pydantic (duh)
+
+Additionally, we provide `grafo` out of the box for convenient workflow building.
+
+## About Grafo
+Grafo (see Recommended Docs below) is a library for building executable DAGs where each node contains a coroutine. Since the DAG abstraction fits particularly well into AI-driven building, we have provided the `BaseWorkflow` class with the following methods:
+- `task` for LLM calling
+- `redirect` to help you manage redirections in your `grafo` workflows
+
+# Examples
+### Simple text:
+```python
+from py_ai_toolkit import AIT
+
+ait = AIT("gpt-5")
+path = "./prompt.md"
+response = ait.chat(path)
+print(response.completion)
+print(response.content)
+```
+
+### Structured response:
+```python
+from py_ai_toolkit import AIT
+from pydantic import BaseModel
+
+class Purchase(BaseModel):
+    product: str
+    quantity: int
+
+ait = AIT("gpt-5")
+path = "./prompt.md" # PROMPT: {{ message }}
+message = "I want to buy 5 apples"
+response = ait.asend(response_model=Fruit, path=path, message=message)
+```
+
+### Structured response with model type injection:
+```python
+from py_ai_toolkit import AIT
+from pydantic import BaseModel
+
+class Purchase(BaseModel):
+    product: str
+    quantity: int
+
+ait = AIT("gpt-5")
+path = "./prompt.md" # PROMPT: {{ message }}
+message = "I want to buy 5 apples"
+available_fruits = ["apple", "banana", "orange"]
+FruitModel = ait.inject_types(Purchase, [
+    ("product", Literal[tuple(available_fruits)])
+])
+response = ait.asend(response_model=Purchase, path=path, message=message)
+```
+
+### Simple workflow:
+```python
+from py_ai_toolkit import AIT, BaseWorkflow, Node
+from pydantic import BaseModel
+
+class Purchase(BaseModel):
+    product: str
+    quantity: int
+
+class Eval(BaseModel):
+    is_valid: bool
+    reasoning: str
+    humanized_failure_reason: str | None
+
+ait = AIT("gpt-5")
+prompts_path = "./"
+message = "I want to buy 5 apples"
+available_fruits = ["apple", "banana", "orange"]
+FruitModel = ait.inject_types(Purchase, [
+    ("product", Literal[tuple(available_fruits)])
+])
+
+class PurchaseWorkflow(BaseWorkflow):
+    def __init__(...):
+        ...
+
+    async def run(self, message) -> Purchase:
+        purchase_node = Node[FruitModel](
+            uuid="fruit purchase node"
+            coroutine=self.task
+            kwargs=dict(
+                path=f"{prompts_path}/purchase.md"
+                response_model=FruitModel
+                message=message
+            )
+        )
+        validation_node = Node[Eval](
+            uuid="purchase eval node"
+            coroutine=self.task
+            kwargs=dict(
+                path=f"{prompts_path}/eval.md"
+                response_model=Eval
+                message=message
+                purchase=lambda: purchase_node.output
+            )
+        )
+        eval_node.on_after_run = (
+            self.redirect,
+            dict(
+                source_node=purchase_node
+                validation_node=validation_node
+            )
+        )
+        await purchase_node.connect(validation_node)
+        executor = TreeExecutor(uuid="Purchase Workflow", roots=[purchase_node])
+        await executor.run()
+
+        if not purchase_node.output or not validation_node.output.is_valid:
+            raise ValueError("Purchase failed.")
+
+        return purchase_node.output
+```
+
+## Recommended Docs
+- `instructor` https://python.useinstructor.com/
+- `jinja2` https://jinja.palletsprojects.com/en/stable/
+- `pydantic` https://docs.pydantic.dev/latest/
+- `grafo` https://github.com/paulomtts/grafo

py_ai_toolkit-0.2.0/README.md

@@ -0,0 +1,138 @@
+# Install
+```
+uv add py-ai-toolkit
+```
+
+# WHAT
+A set of tools for easily interacting with LLMs.
+
+# WHY
+Building AI-driven software leans upon a number of utilities, such as prompt building and LLM calling via HTTP requests. Additionally, writing agents and workflows can prove particularly challenging using conventional code structures.
+
+# HOW
+This simple library offers a set of predefined functions for:
+- Easy prompting - you need only provide a path
+- Calling LLMs - instructor takes care of that for us
+- Modifying response models - we use Pydantic (duh)
+
+Additionally, we provide `grafo` out of the box for convenient workflow building.
+
+## About Grafo
+Grafo (see Recommended Docs below) is a library for building executable DAGs where each node contains a coroutine. Since the DAG abstraction fits particularly well into AI-driven building, we have provided the `BaseWorkflow` class with the following methods:
+- `task` for LLM calling
+- `redirect` to help you manage redirections in your `grafo` workflows
+
+# Examples
+### Simple text:
+```python
+from py_ai_toolkit import AIT
+
+ait = AIT("gpt-5")
+path = "./prompt.md"
+response = ait.chat(path)
+print(response.completion)
+print(response.content)
+```
+
+### Structured response:
+```python
+from py_ai_toolkit import AIT
+from pydantic import BaseModel
+
+class Purchase(BaseModel):
+    product: str
+    quantity: int
+
+ait = AIT("gpt-5")
+path = "./prompt.md" # PROMPT: {{ message }}
+message = "I want to buy 5 apples"
+response = ait.asend(response_model=Fruit, path=path, message=message)
+```
+
+### Structured response with model type injection:
+```python
+from py_ai_toolkit import AIT
+from pydantic import BaseModel
+
+class Purchase(BaseModel):
+    product: str
+    quantity: int
+
+ait = AIT("gpt-5")
+path = "./prompt.md" # PROMPT: {{ message }}
+message = "I want to buy 5 apples"
+available_fruits = ["apple", "banana", "orange"]
+FruitModel = ait.inject_types(Purchase, [
+    ("product", Literal[tuple(available_fruits)])
+])
+response = ait.asend(response_model=Purchase, path=path, message=message)
+```
+
+### Simple workflow:
+```python
+from py_ai_toolkit import AIT, BaseWorkflow, Node
+from pydantic import BaseModel
+
+class Purchase(BaseModel):
+    product: str
+    quantity: int
+
+class Eval(BaseModel):
+    is_valid: bool
+    reasoning: str
+    humanized_failure_reason: str | None
+
+ait = AIT("gpt-5")
+prompts_path = "./"
+message = "I want to buy 5 apples"
+available_fruits = ["apple", "banana", "orange"]
+FruitModel = ait.inject_types(Purchase, [
+    ("product", Literal[tuple(available_fruits)])
+])
+
+class PurchaseWorkflow(BaseWorkflow):
+    def __init__(...):
+        ...
+
+    async def run(self, message) -> Purchase:
+        purchase_node = Node[FruitModel](
+            uuid="fruit purchase node"
+            coroutine=self.task
+            kwargs=dict(
+                path=f"{prompts_path}/purchase.md"
+                response_model=FruitModel
+                message=message
+            )
+        )
+        validation_node = Node[Eval](
+            uuid="purchase eval node"
+            coroutine=self.task
+            kwargs=dict(
+                path=f"{prompts_path}/eval.md"
+                response_model=Eval
+                message=message
+                purchase=lambda: purchase_node.output
+            )
+        )
+        eval_node.on_after_run = (
+            self.redirect,
+            dict(
+                source_node=purchase_node
+                validation_node=validation_node
+            )
+        )
+        await purchase_node.connect(validation_node)
+        executor = TreeExecutor(uuid="Purchase Workflow", roots=[purchase_node])
+        await executor.run()
+
+        if not purchase_node.output or not validation_node.output.is_valid:
+            raise ValueError("Purchase failed.")
+
+        return purchase_node.output
+```
+
+## Recommended Docs
+- `instructor` https://python.useinstructor.com/
+- `jinja2` https://jinja.palletsprojects.com/en/stable/
+- `pydantic` https://docs.pydantic.dev/latest/
+- `grafo` https://github.com/paulomtts/grafo

py_ai_toolkit-0.2.0/py_ai_toolkit/__init__.py

@@ -0,0 +1,18 @@
+__version__ = "0.2.0"
+
+from grafo import Chunk, Node, TreeExecutor
+
+from .core.base import BaseWorkflow
+from .core.domain.errors import BaseError
+from .core.domain.interfaces import CompletionResponse
+from .core.tools import PyAIToolkit
+
+__all__ = [
+    "PyAIToolkit",
+    "CompletionResponse",
+    "Node",
+    "TreeExecutor",
+    "Chunk",
+    "BaseWorkflow",
+    "BaseError",
+]

py_ai_toolkit-0.2.0/py_ai_toolkit/adapters/__init__.py

@@ -0,0 +1,5 @@
+from .instructor_adapter import InstructorAdapter
+from .jinja2_adapter import Jinja2Adapter
+from .pydantic_adapter import PydanticAdapter
+
+__all__ = ["Jinja2Adapter", "PydanticAdapter", "InstructorAdapter"]

py_ai_toolkit-0.2.0/py_ai_toolkit/adapters/instructor_adapter.py

@@ -0,0 +1,125 @@
+from http import HTTPStatus
+from typing import AsyncGenerator, Type
+
+import instructor
+from openai import AsyncOpenAI
+from openai.types.chat import ChatCompletion, ChatCompletionChunk
+
+from py_ai_toolkit.core.domain.errors import LLMAdapterError
+from py_ai_toolkit.core.domain.interfaces import CompletionResponse, T
+from py_ai_toolkit.core.ports import LLMPort
+
+
+class InstructorAdapter(LLMPort):
+    """
+    Instructor implementation of the LLM port.
+    """
+
+    def __init__(
+        self,
+        model: str,
+        embedding_model: str,
+        api_key: str,
+        base_url: str | None = None,
+    ):
+        self._model = model
+        self._embedding_model = embedding_model
+
+        client_kwargs = dict(
+            api_key=api_key,
+        )
+        if not base_url:
+            client_kwargs["base_url"] = "http://localhost:11434/v1"
+        self.openai_client = AsyncOpenAI(**client_kwargs)  # type: ignore
+        self.client = instructor.from_openai(
+            client=self.openai_client,
+            mode=instructor.Mode.JSON,
+        )
+
+    async def chat(self, messages: list[dict[str, str]]) -> CompletionResponse:
+        """
+        Sends a message to the LLM and returns a structured response.
+
+        Args:
+            messages (list[dict[str, str]]): The messages to generate a response to
+
+        Returns:
+            str: The response from the LLM
+        """
+        output: ChatCompletion = await self.openai_client.chat.completions.create(
+            model=self._model,
+            messages=messages,
+            stream=False,
+        )
+        response = output.choices[0].message.content
+        if not response:
+            raise LLMAdapterError(
+                status_code=HTTPStatus.SERVICE_UNAVAILABLE.value,
+                message="No response from the model",
+            )
+        return CompletionResponse(
+            completion=output,
+            content=response,
+        )
+
+    async def stream(
+        self, messages: list[dict[str, str]]
+    ) -> AsyncGenerator[CompletionResponse, None]:
+        """
+        Streams text outputs from the model.
+
+        Args:
+            messages (list[dict[str, str]]): The messages to generate a response to
+
+        Returns:
+            AsyncGenerator[str, None]: The response from the LLM
+        """
+        output: AsyncGenerator[
+            ChatCompletionChunk, None
+        ] = await self.openai_client.chat.completions.create(
+            model=self._model,
+            messages=messages,
+            stream=True,
+        )
+        async for chunk in output:
+            response = chunk.choices[0].delta.content
+            if not response:
+                continue
+            yield CompletionResponse(
+                completion=chunk,
+                content=response,
+            )
+
+    async def asend(
+        self,
+        messages: list[dict[str, str]],
+        response_model: Type[T],
+    ) -> CompletionResponse[T]:
+        """
+        Sends a message to the LLM asynchronously and returns a structured response.
+
+        Args:
+            messages (list[dict[str, str]]): The messages to generate a response to
+            response_model (Type[T]): The model to return the response as
+
+        Returns:
+            CompletionResponse[T]: The response from the LLM
+        """
+
+        (
+            instance,
+            completion,
+        ) = await self.client.chat.completions.create_with_completion(
+            response_model=response_model,
+            model=self._model,
+            messages=messages,
+        )
+        if not instance:
+            raise LLMAdapterError(
+                status_code=HTTPStatus.SERVICE_UNAVAILABLE.value,
+                message="No response content from the model",
+            )
+        return CompletionResponse(
+            completion=completion,
+            content=instance,
+        )

py_ai_toolkit-0.2.0/py_ai_toolkit/adapters/jinja2_adapter.py

@@ -0,0 +1,40 @@
+from typing import Any, Optional
+
+from jinja2 import Environment
+
+from py_ai_toolkit.core.domain.errors import FormatterAdapterError
+from py_ai_toolkit.core.ports import FormatterPort
+
+
+class Jinja2Adapter(FormatterPort):
+    """
+    Jinja2 implementation of the formatter port.
+    Supports only Markdown files.
+    """
+
+    def __init__(self):
+        self.env = Environment()
+
+    def _load_prompt(self, path: str) -> str:
+        with open(path, "r", encoding="utf-8") as file:
+            return file.read()
+
+    def render(
+        self,
+        path: str | None = None,
+        prompt: str | None = None,
+        input: Optional[dict[str, Any]] = None,
+    ) -> str:
+        """
+        Render a Markdown template from a path with variables.
+
+        Args:
+            path (str | None): The directory path where the file is located
+            prompt (str | None): The prompt to render
+            input (Optional[dict[str, Any]]): Variables to pass to the template
+        """
+        if not path and not prompt:
+            raise FormatterAdapterError("Either path or prompt must be provided")
+        base_prompt = prompt or self._load_prompt(path)
+        template = self.env.from_string(base_prompt)
+        return template.render(**(input or {}))

py_ai_toolkit-0.2.0/py_ai_toolkit/adapters/pydantic_adapter.py

@@ -0,0 +1,71 @@
+import re
+from typing import Any, Type, TypeVar
+
+from pydantic import BaseModel, Field, create_model
+from pydantic_core import PydanticUndefined
+
+from py_ai_toolkit.core.ports import ModellerPort
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class PydanticAdapter(ModellerPort):
+    """
+    Service for creating Pydantic models from schemas.
+    """
+
+    def _normalize(self, text: str) -> str:
+        """
+        Normalizes the text to a valid Pydantic model field name.
+        """
+        return re.sub(r"[^a-zA-Z0-9_]", "", text)
+
+    def _pascal_case(self, string: str) -> str:
+        """
+        Converts a string to pascal case.
+        """
+        normalized = re.sub(r"[^a-zA-Z0-9\s]", " ", string).strip()
+        return "".join(word.capitalize() for word in normalized.split())
+
+    def inject_types(
+        self,
+        model: Type[T],
+        fields: list[tuple[str, Any]],
+    ) -> Type[T]:
+        """
+        Injects field types into a model.
+        """
+        return create_model(
+            model.__name__ + "Model",
+            __base__=(model,),
+            __doc__=model.__doc__,
+            **{
+                field_name: (
+                    field_type,
+                    Field(
+                        description=model.model_fields[field_name].description,
+                        examples=model.model_fields[field_name].examples,
+                    ),
+                )
+                for (field_name, field_type) in fields
+            },  # type: ignore
+        )
+
+    def reduce_model_schema(
+        self, model: Type[T], include_description: bool = True
+    ) -> str:
+        """
+        Reduces the model schema into version with less tokens. Helpful for reducing prompt noise.
+        """
+        reduced_schema = []
+        for field, info in model.model_fields.items():
+            reduced_schema.append(
+                f"{field}({info.annotation}"
+                + (
+                    f", default={info.default})"
+                    if info.default is not PydanticUndefined
+                    else ")"
+                )
+                + (f": {info.description}" if include_description else "")
+            )
+        return "\n".join(reduced_schema)