pyagentic-core 1.0.0__tar.gz

pyagentic_core-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ryan Mikulec
+
+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.

pyagentic_core-1.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: pyagentic-core
+Version: 1.0.0
+Summary: Build LLM Agents in a Pythonic way
+Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorlog>=6.9.0
+Requires-Dist: ipykernel>=6.29.5
+Requires-Dist: openai>=1.93.2
+Requires-Dist: typeguard>=4.4.4
+Dynamic: license-file
+
+# PyAgentic
+
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Tests](https://github.com/rmikulec/pyagentic/workflows/Tests/badge.svg?branch=main)](https://github.com/rmikulec/pyAgentic/actions/workflows/testing.yml?query=branch%3Amain)
+
+A declarative framework for building AI agents with OpenAI integration. PyAgentic provides a clean, type-safe way to create intelligent agents using Python's metaclass system and modern async patterns.
+
+##  Features
+
+- **Declarative Agent Definition** - Define agents using simple class-based syntax
+- **Type Safety** - Full typing support with Pydantic integration
+- **Tool Integration** - Easy function decoration for agent capabilities
+- **Context Management** - Sophisticated context handling with lifecycle management
+- **OpenAI Integration** - Native support for OpenAI's API with automatic schema generation
+- **Async Support** - Built-in async/await support for scalable applications
+- **Extensible** - Clean architecture for custom tools, context types, and validations
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install pyagentic-core
+```
+
+### Basic Example
+
+```python
+from pyagentic import Agent, tool, ContextItem
+from typing import List
+
+class WeatherAgent(Agent):
+    """An agent that provides weather information."""
+    
+    location: str = ContextItem(description="Current location")
+    
+    @tool
+    def get_weather(self, city: str) -> str:
+        """Get current weather for a city."""
+        # Your weather API logic here
+        return f"The weather in {city} is sunny and 75°F"
+    
+    @tool
+    def get_forecast(self, city: str, days: int = 5) -> List[str]:
+        """Get weather forecast for multiple days."""
+        return [f"Day {i+1}: Partly cloudy" for i in range(days)]
+
+# Create and use the agent
+agent = WeatherAgent(location="San Francisco")
+response = await agent.run("What's the weather like in New York?")
+print(response)
+```
+
+
+## Project Structure
+
+```
+pyagentic/
+├── pyagentic/           # Core framework code
+│   ├── _base/           # Internal implementation
+│   └── __init__.py      # Public API
+├── tests/               # Test suite
+│   ├── _base/           # Core tests
+│   ├── integration/     # Integration tests
+│   └── performance/     # Performance tests
+├── examples/            # Example agents
+├── templates/           # Agent templates
+├── docs/                # Documentation
+├── scripts/             # Utility scripts
+└── notebooks/           # Jupyter notebooks
+```
+
+## Contributing
+
+Contributions are welcome! Details coming soon.
+
+### Development Setup
+
+```bash
+# Install dependencies
+uv sync --group dev
+
+# Formatting
+uv run black -l99 pyagentic
+
+# Linting
+uv run flake8 --max-line-length 99 pyagentic
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pyagentic_core-1.0.0/README.md

@@ -0,0 +1,94 @@
+# PyAgentic
+
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Tests](https://github.com/rmikulec/pyagentic/workflows/Tests/badge.svg?branch=main)](https://github.com/rmikulec/pyAgentic/actions/workflows/testing.yml?query=branch%3Amain)
+
+A declarative framework for building AI agents with OpenAI integration. PyAgentic provides a clean, type-safe way to create intelligent agents using Python's metaclass system and modern async patterns.
+
+##  Features
+
+- **Declarative Agent Definition** - Define agents using simple class-based syntax
+- **Type Safety** - Full typing support with Pydantic integration
+- **Tool Integration** - Easy function decoration for agent capabilities
+- **Context Management** - Sophisticated context handling with lifecycle management
+- **OpenAI Integration** - Native support for OpenAI's API with automatic schema generation
+- **Async Support** - Built-in async/await support for scalable applications
+- **Extensible** - Clean architecture for custom tools, context types, and validations
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install pyagentic-core
+```
+
+### Basic Example
+
+```python
+from pyagentic import Agent, tool, ContextItem
+from typing import List
+
+class WeatherAgent(Agent):
+    """An agent that provides weather information."""
+    
+    location: str = ContextItem(description="Current location")
+    
+    @tool
+    def get_weather(self, city: str) -> str:
+        """Get current weather for a city."""
+        # Your weather API logic here
+        return f"The weather in {city} is sunny and 75°F"
+    
+    @tool
+    def get_forecast(self, city: str, days: int = 5) -> List[str]:
+        """Get weather forecast for multiple days."""
+        return [f"Day {i+1}: Partly cloudy" for i in range(days)]
+
+# Create and use the agent
+agent = WeatherAgent(location="San Francisco")
+response = await agent.run("What's the weather like in New York?")
+print(response)
+```
+
+
+## Project Structure
+
+```
+pyagentic/
+├── pyagentic/           # Core framework code
+│   ├── _base/           # Internal implementation
+│   └── __init__.py      # Public API
+├── tests/               # Test suite
+│   ├── _base/           # Core tests
+│   ├── integration/     # Integration tests
+│   └── performance/     # Performance tests
+├── examples/            # Example agents
+├── templates/           # Agent templates
+├── docs/                # Documentation
+├── scripts/             # Utility scripts
+└── notebooks/           # Jupyter notebooks
+```
+
+## Contributing
+
+Contributions are welcome! Details coming soon.
+
+### Development Setup
+
+```bash
+# Install dependencies
+uv sync --group dev
+
+# Formatting
+uv run black -l99 pyagentic
+
+# Linting
+uv run flake8 --max-line-length 99 pyagentic
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pyagentic_core-1.0.0/pyagentic/__init__.py

@@ -0,0 +1,6 @@
+from pyagentic._base._agent import Agent
+from pyagentic._base._params import Param, ParamInfo
+from pyagentic._base._tool import tool
+from pyagentic._base._context import computed_context, ContextRef, ContextItem
+
+__all__ = ["Agent", "Param", "ParamInfo", "tool", "computed_context", "ContextRef", "ContextItem"]

pyagentic_core-1.0.0/pyagentic/_base/_agent.py

@@ -0,0 +1,190 @@
+import inspect
+import json
+import openai
+from typing import Callable, Any, TypeVar, ClassVar
+
+from pyagentic.logging import get_logger
+from pyagentic._base._tool import _ToolDefinition
+from pyagentic._base._context import ContextItem
+from pyagentic._base._metaclasses import AgentMeta
+from pyagentic.updates import AiUpdate, Status, EmitUpdate, ToolUpdate
+
+logger = get_logger(__name__)
+
+
+async def _safe_run(fn, *args, **kwargs):
+    """
+    Helper function to always run a function, async or not
+    """
+    if inspect.iscoroutinefunction(fn):
+        result = await fn(*args, **kwargs)
+    else:
+        result = fn(*args, **kwargs)
+    return result
+
+
+class Agent(metaclass=AgentMeta):
+    __abstract_base__ = True
+    """
+    Base agent class to be extended in order to define a new Agent
+
+    Agent defintion requires the use of special function decorators in order to define the
+        behavior of the agent.
+
+        - @tool: Declares a method as a tool, allowing the agent to use it
+
+    Agents also have default arguements that can be declared on initiation
+
+    Args:
+        - model (str): The OpenAI model that will be used for inference. Defaults to value
+            found in `geo_assistant.config`
+        - emitter (Callable): A function that will be called to recieve intermittant information
+            about the agent's process. A common use case is that of a websocket, to be able
+            to recieve information about the process as it is happening
+    """
+    # Class Attributes
+    __tool_defs__: ClassVar[dict[str, _ToolDefinition]]
+    __context_attrs__: ClassVar[dict[str, tuple[TypeVar, ContextItem]]]
+    __system_message__: ClassVar[str]
+    __input_template__: ClassVar[str] = None
+
+    # Base Attributes
+    model: str
+    api_key: str
+    emitter: Callable[[Any], str] = None
+
+    def __post_init__(self):
+        self.client: openai.AsyncOpenAI = openai.AsyncOpenAI(api_key=self.api_key)
+
+    async def _process_tool_call(self, tool_call) -> bool:
+        if tool_call.type != "function_call":
+            return False
+        self.context._messages.append(tool_call)
+        logger.info(f"Calling {tool_call.name} with kwargs: {tool_call.arguments}")
+        # Lookup the bound method
+        try:
+            tool_def = self.__tool_defs__[tool_call.name]
+            handler = getattr(self, tool_call.name)
+        except KeyError:
+            return f"Tool {tool_call.name} not found"
+        kwargs = json.loads(tool_call.arguments)
+
+        # Run the tool, emitting updates
+        try:
+            if self.emitter:
+                await _safe_run(
+                    self.emitter,
+                    ToolUpdate(
+                        status=Status.PROCESSING, tool_call=tool_call.name, tool_args=kwargs
+                    ),
+                )
+
+            compiled_args = tool_def.compile_args(**kwargs)
+            result = await _safe_run(handler, **compiled_args)
+        except Exception as e:
+            logger.exception(e)
+            result = f"Tool `{tool_call.name}` failed: {e}. Please kindly state to the user that is failed, provide context, and ask if they want to try again."  # noqa E501
+            if self.emitter:
+                await _safe_run(
+                    self.emitter,
+                    ToolUpdate(status=Status.ERROR, tool_call=tool_call.name, tool_args=kwargs),
+                )
+
+        # Record output for LLM
+        self.context._messages.append(
+            {"type": "function_call_output", "call_id": tool_call.call_id, "output": result}
+        )
+        return True
+
+    async def _build_tool_defs(self) -> list[dict]:
+        tool_defs = []
+        # iterate through registered tools
+        for tool_def in self.__tool_defs__.values():
+            # Check if any of the tool params use a ContextRef
+            # convert to openai schema
+            tool_defs.append(tool_def.to_openai(self.context))
+        return tool_defs
+
+    async def run(self, input_: str) -> str:
+        """
+        Run the agent with any given input
+
+        Parameters:
+            input_(str): The user input for the agent to process
+
+        Returns:
+            str: The output of the agent
+        """
+
+        # Generate and insert the new system message
+        self.context.add_user_message(input_)
+
+        # Create the tool list
+        tool_defs = await self._build_tool_defs()
+
+        # Begin the first pass on generating a response from openai
+        if self.emitter:
+            await _safe_run(
+                self.emitter,
+                EmitUpdate(
+                    status=Status.GENERATING,
+                ),
+            )
+        try:
+            response = await self.client.responses.create(
+                model=self.model,
+                input=self.context.messages,
+                tools=tool_defs,
+            )
+            reasoning = [rx.to_dict() for rx in response.output if rx.type == "reasoning"]
+            tool_calls = [rx for rx in response.output if rx.type == "function_call"]
+        except Exception as e:
+            logger.exception(e)
+            # On failure, emit an udpate, update the messages, and return a standard message
+            if self.emitter:
+                await _safe_run(
+                    self.emitter,
+                    EmitUpdate(
+                        status=Status.ERROR,
+                    ),
+                )
+            self.context._messages.append(
+                {"role": "assistant", "content": "Failed to generate a response"}
+            )
+            return f"OpenAI failed to generate a response: {e}"
+
+        if reasoning:
+            self.context._messages.extend(reasoning)
+
+        # Dispatch any tool calls
+        made_calls = False
+        for tool_call in tool_calls:
+            made_calls = made_calls or (await self._process_tool_call(tool_call))
+
+        # If tools ran, re-invoke LLM for natural reply
+        if made_calls:
+            try:
+                response = await self.client.responses.create(
+                    model=self.model,
+                    input=self.context.messages,
+                )
+            except Exception as e:
+                logger.exception(e)
+                if self.emitter:
+                    await _safe_run(
+                        self.emitter, EmitUpdate(status=Status.ERROR, message="Generation failed")
+                    )
+                self.context._messages.append(
+                    {"role": "assistant", "content": "Failed to generate a response"}
+                )
+                return f"OpenAI failed to generate a response: {e}"
+
+        # Parse and finalize the Ai Response
+        ai_message = response.output_text
+
+        self.context._messages.append({"role": "assistant", "content": ai_message})
+
+        if self.emitter:
+            await _safe_run(self.emitter, AiUpdate(status=Status.SUCCEDED, message=ai_message))
+
+        return ai_message

pyagentic_core-1.0.0/pyagentic/_base/_context.py

@@ -0,0 +1,216 @@
+import functools
+from typing import Any, Callable, Type, Self
+from dataclasses import dataclass, make_dataclass, field, asdict
+
+from pyagentic._base._exceptions import InvalidContextRefNotFoundInContext
+
+
+@dataclass
+class ContextItem:
+    """
+    A `ContextItem` is used to signal that a class attribute can be used in the context
+    of an agent. Any of these values can be referenced in:
+        - the agent's `instructions`
+        - the agent's `input_template`
+        - any `ContextRef` used in the Agent (e.g., in a `ParamInfo`)
+        - the constructor of the Agent itself
+
+    Args:
+        default (Any, optional):
+            The default value for this context item if no explicit value is provided.
+            Defaults to `None`.
+        default_factory (Callable[[], Any], optional):
+            A zero-argument factory function that produces a default value.
+            If provided, its return value takes precedence over `default`.
+            Defaults to `None`.
+    """
+
+    default: Any = None
+    default_factory: Callable = None
+
+    def __post_init__(self):
+        if not (self.default or self.default_factory):
+            raise AttributeError("default or default_factory must be given")
+
+    def get_default_value(self):
+        if self.default_factory:
+            return self.default_factory()
+        else:
+            return self.default
+
+
+class computed_context:
+    """
+    Descriptor used to mark a method in an Agent as a computed context.
+
+    Computed contexts work very similarly to Python's `@property` descriptor: they are
+    re-computed each time they're accessed. When a computed context appears in:
+
+      - the agent's `instructions`, its value will be refreshed on every call to the agent,
+        updating the system message with the latest value.
+      - the agent's `input_template`, its value will be refreshed each time a new user message is
+        added, updating the prompt accordingly.
+
+    Args:
+        func (Callable[[Agent], Any]):
+            The method on the Agent class that computes and returns the context value.
+            It will be called with the agent instance each time the context is accessed.
+    """
+
+    def __init__(self, fget):
+        functools.update_wrapper(self, fget)
+        self.fget = fget
+        self._is_context = True
+
+    def __set_name__(self, owner, name):
+        self.name = name
+
+    def __get__(self, instance, owner=None):
+        # when accessed on the class, return the descriptor itself
+        if instance is None:
+            return self
+        # when accessed on the instance, run the function against the *context* object
+        # (we’ll inject this descriptor onto the Context class)
+        return self.fget(instance)
+
+
+@dataclass(repr=True)
+class _AgentContext:
+    """
+    Base context class for agents; uses dataclass for auto-generated init/signature.
+    """
+
+    instructions: str
+    input_template: str = None
+    _messages: list = field(default_factory=list)
+
+    def as_dict(self) -> dict:
+        """
+        Exports the context as a dictionary. This dictionary is not serialized, so
+        any `ContextItem` or `computed_context` remains their original type.
+
+        Returns:
+            - dict: A dictionary containing all `ContextItem` and `computed_context`
+                for later processing.
+        """
+
+        data = asdict(self)
+
+        # tinject every computed_context value
+        for name, attr in type(self).__dict__.items():
+            if getattr(attr, "_is_context", False):
+                data[name] = getattr(self, name)
+        return data
+
+    @property
+    def system_message(self) -> str:
+        """
+        The current formatted system_message
+        """
+        # start with all the normal dataclass fields
+
+        # now format your instruction template
+        return self.instructions.format(**self.as_dict())
+
+    @property
+    def messages(self) -> list[dict[str, str]]:
+        """
+        List of openai-ready messages with the most up-to-date system message
+        """
+        messages = self._messages.copy()
+        messages.insert(0, {"role": "system", "content": self.system_message})
+        return messages
+
+    def add_user_message(self, message: str):
+        """
+        Add a user message to the message list. If a `input_template` is given then
+            the message will be formatted in it as well as any context used in the template.
+
+        To use the user message in the template, place the key `user_message`.
+
+        Args:
+            message(str): The user message to be added.
+        """
+
+        if self.input_template:
+            data = self.as_dict()
+            data["user_message"] = message
+            content = self.input_template.format(**data)
+        else:
+            content = message
+        self._messages.append({"role": "user", "content": content})
+
+    def get(self, name: str) -> Any:
+        """
+        Retrieves an item from the context.
+
+        Args:
+            name(str): The name of the item
+
+        Returns:
+            Any: The item. If it is a computed context item, then it is computed upon retrieval.
+        """
+        try:
+            return self.as_dict()[name]
+        except KeyError:
+            raise InvalidContextRefNotFoundInContext(name)
+
+    @classmethod
+    def make_ctx_class(cls, name: str, ctx_map: dict[str, tuple[Type[Any], Any]]) -> Type[Self]:
+        """
+        Dynamically create a dataclass subclass with typed context fields.
+
+        Args:
+            name: base name for the new class (e.g. 'MyAgent').
+            ctx_map: mapping of field name to (type, ContextItem).
+
+        Returns:
+            A new dataclass type 'NameContext'.
+        """
+        dc_fields = []  # for actual dataclass fields (ContextItem)
+        namespace: dict[str, Any] = {"__module__": cls.__module__}
+
+        for field_name, (type_, info) in ctx_map.items():
+            if isinstance(info, ContextItem):
+                # ---- your existing logic for setting defaults ----
+                if info.default_factory is not None:
+                    dc_def = field(default_factory=info.default_factory)
+                else:
+                    dc_def = field(default=info.default)
+                dc_fields.append((field_name, type_, dc_def))
+
+            elif isinstance(info, computed_context):
+                # stick the descriptor straight into the namespace
+                namespace[field_name] = info
+                # also record its type for annotation
+                namespace.setdefault("__annotations__", {})[field_name] = type_
+
+            else:
+                raise RuntimeError(f"Unexpected ctx_map entry for {field_name!r}: {info!r}")
+
+        # now build the dataclass
+        return make_dataclass(
+            cls_name=f"{name}Context",
+            fields=dc_fields,
+            bases=(cls,),
+            namespace=namespace,
+        )
+
+
+class ContextRef:
+    """
+    A placeholder pointing at some attribute or method
+    on the agent’s context, to be resolved at schema-build time.
+    """
+
+    def __init__(self, path: str):
+        self.path = path  # dot-notation into agent.context
+
+    def resolve(self, context: _AgentContext) -> Any:
+        val = context
+        for part in self.path.split("."):
+            val = getattr(val, part)
+            # if it’s wrapped in our Context helper, drill into .value
+            if hasattr(val, "value"):
+                val = val.value
+        return val() if callable(val) else val

pyagentic_core-1.0.0/pyagentic/_base/_exceptions.py

@@ -0,0 +1,39 @@
+class ToolDeclarationFailed(Exception):
+
+    def __init__(self, tool_name, message):
+        message = f"Tool declaration failed for {tool_name}" f"{message}"
+        super().__init__(message)
+
+
+class SystemMessageNotDeclared(Exception):
+    def __init__(self):
+        super().__init__(
+            "System message not declared on agent. Agent must be declared with `__system_message__`"  # noqa E501
+        )
+
+
+class UnexpectedContextItemType(Exception):
+    def __init__(self, name, expected, recieved):
+        message = (
+            f"Unexpected value provided for `{name}`. "
+            f"Expected: {expected} - Recieved: {recieved}"
+        )
+        super().__init__(message)
+
+
+class InvalidContextRefNotFoundInContext(Exception):
+    def __init__(self, name):
+        message = (
+            f"'{name}' not found in context. "
+            "Make sure it is either declared as a `ContextItem` or using `computed_context`"
+        )
+        super().__init__(message)
+
+
+class InvalidContextRefMismatchTyping(Exception):
+    def __init__(self, ref_path, field_name, recieved_type, expected_type):
+        message = (
+            f"ContextRef('{ref_path}') for {self.__class__.__name__}.{field_name}  "
+            f"is of type {recieved_type}, expected {expected_type}"
+        )
+        super().__init__(message)