pyagentic-core 1.0.0__py3-none-any.whl

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/_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/_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/_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)

pyagentic/_base/_metaclasses.py

@@ -0,0 +1,153 @@
+import inspect
+from typing import dataclass_transform, TypeVar
+from typeguard import check_type
+
+from pyagentic._base._exceptions import SystemMessageNotDeclared, UnexpectedContextItemType
+from pyagentic._base._context import _AgentContext, ContextItem, computed_context
+from pyagentic._base._tool import _ToolDefinition
+
+
+@dataclass_transform(field_specifiers=(ContextItem,))
+class AgentMeta(type):
+    """
+    Metaclass that applies only to Agent subclasses:
+      - Ensures @system_message was declared
+      - Collects @tool definitions and ContextItem attributes
+      - Initializes class __tool_defs__ and __context_items__
+      - Dynamically injects an __init__ signature based on class __annotations__
+    """
+
+    @staticmethod
+    def _extract_tool_defs(namespace) -> dict[str, _ToolDefinition]:
+        """
+        Extracts tool definitions from a given namespace
+
+        Any method with the `@tool` descriptor will be attached to the `__tool_defs__` class
+            attribute
+        """
+        tools = {}
+        for attr_name, attr_value in namespace.items():
+            if hasattr(attr_value, "__tool_def__"):
+                tools[attr_name] = attr_value.__tool_def__
+        return tools
+
+    @staticmethod
+    def _extract_annotations(bases, namespace) -> dict[str, TypeVar]:
+        """
+        Extracts all annotations from current class and all its subclasses. Combines them into
+            one dictionary, with class order respected (subclasses overide parent classes.)
+        """
+        annotations = {}
+        for base in reversed(bases):
+            if hasattr(base, "__annotations__"):
+                for name, type_ in base.__annotations__.items():
+                    if not name.startswith("__"):
+                        annotations[name] = type_
+        for name, type_ in namespace.get("__annotations__", {}).items():
+            if not name.startswith("__"):
+                annotations[name] = type_
+        return annotations
+
+    @staticmethod
+    def _extract_context_attrs(annotations, namespace) -> dict[str, tuple[TypeVar, ContextItem]]:
+        """
+        Extracts any class field from annotations and namespace where the value is that of
+            `ContextItem`, these will later be appeneded to the agents context. This will return
+            both the type and the user defined context item.
+        """
+        context_attrs = {}
+        for attr_name, attr_type in annotations.items():
+            default = namespace.get(attr_name, None)
+            if isinstance(default, ContextItem):
+                context_attrs[attr_name] = (attr_type, default)
+
+        for name, value in namespace.items():
+            if getattr(value, "_is_context", False):
+                context_attrs[name] = (computed_context, value)
+        return context_attrs
+
+    @staticmethod
+    def _build_init_signature(cls) -> inspect.Signature:
+        """
+        Builds the signature for the classes __init__, injecting any context item attributes
+            defined by the user properly into the inits signature. This allows IDE's to be able
+            to recognize user-defined class attributes when initializing a class.
+        """
+        params = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)]
+        for field_name, field_type in cls.__annotations__.items():
+            if field_name in cls.__context_attrs__:
+                default_val = cls.__context_attrs__[field_name][1].get_default_value()
+            else:
+                default_val = getattr(cls, field_name, inspect._empty)
+            param = inspect.Parameter(
+                field_name,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=default_val,
+                annotation=field_type,
+            )
+            params.append(param)
+        return inspect.Signature(params)
+
+    @staticmethod
+    def _build_init(sig):
+        """
+        Builds the init function for the class. This init will automatically have user-defined
+            context items as arguements, allow for easy initialization of agents for a variety
+            of different tasks.
+        """
+
+        def __init__(self, *args, **kwargs):  # type: ignore
+            ContextClass = _AgentContext.make_ctx_class(
+                name=self.__class__.__name__, ctx_map=self.__context_attrs__
+            )
+
+            context_kwargs = {}
+            for attr_name, (attr_type, attr_default) in self.__context_attrs__.items():
+                if attr_type == computed_context:
+                    continue
+                if attr_name in kwargs:
+                    val = kwargs[attr_name]
+                    if (not check_type(val, attr_type)):
+                        raise UnexpectedContextItemType(
+                            name=attr_name, expected=attr_type, recieved=type(val)
+                        )
+                    context_kwargs[attr_name] = val
+                else:
+                    context_kwargs[attr_name] = attr_default.get_default_value()
+
+            self.context = ContextClass(
+                instructions=self.__system_message__,
+                input_template=self.__input_template__,
+                **context_kwargs,
+            )
+
+            bound = sig.bind(self, *args, **kwargs)
+            for name, val in list(bound.arguments.items())[1:]:  # skip 'self'
+                if name in self.__context_attrs__:
+                    pass
+                setattr(self, name, val)
+
+            self.__post_init__()
+
+        __init__.__signature__ = sig  # type: ignore
+        return __init__
+
+    def __new__(mcs, name, bases, namespace, **kwargs):
+        cls = super().__new__(mcs, name, bases, namespace, **kwargs)
+
+        if namespace.get("__abstract_base__", False):
+            return cls
+
+        if "__system_message__" not in namespace:
+            raise SystemMessageNotDeclared()
+
+        cls.__tool_defs__ = mcs._extract_tool_defs(namespace)
+
+        cls.__annotations__ = mcs._extract_annotations(bases, namespace)
+
+        cls.__context_attrs__ = mcs._extract_context_attrs(cls.__annotations__, namespace)
+
+        sig = mcs._build_init_signature(cls)
+
+        cls.__init__ = mcs._build_init(sig)
+        return cls

pyagentic/_base/_params.py

@@ -0,0 +1,138 @@
+from dataclasses import dataclass
+from collections import defaultdict
+from typing import get_type_hints, Any, List, Dict, Type
+
+from pyagentic._base._resolver import ContextualMixin, MaybeContext
+from pyagentic._base._context import _AgentContext
+
+# simple mapping from Python types to JSON Schema/OpenAI types
+_TYPE_MAP: Dict[Type[Any], str] = {
+    int: "integer",
+    float: "number",
+    str: "string",
+    bool: "boolean",
+}
+
+
+@dataclass
+class ParamInfo(ContextualMixin):
+    """
+    Declare metadata for parameters in tool declarations and/or Parameter declarations.
+
+    Attributes:
+        description (str | None): A human-readable description of the parameter.
+        required (bool): Whether this parameter must be provided by the user.
+        default (Any): The default value to use if none is provided.
+        values (list[str]): values to limit the input of this parameter. If used, the
+            agent is forced to use on the the values in the list.
+
+    Context-Ready Attributes:
+        These attributes can be given a `ContextRef` to link them to any context items in
+        the agent.
+
+         - description
+         - default
+         - values
+    """
+
+    description: MaybeContext[str] = None
+    required: bool = False
+    default: MaybeContext[Any] = None
+    values: MaybeContext[list[str]] = None
+
+
+class Param:
+    """
+    Base class for defining structured parameters that can be converted
+    into OpenAI-compatible JSON schema entries.
+
+    Subclasses should declare class attributes with type annotations,
+    optionally assigning a ParamInfo instance or a raw default value.
+
+    On subclass creation, __attributes__ is populated mapping field names
+    to (type, ParamInfo) pairs. Instances perform simple type-checked
+    assignment and reject unknown fields.
+    """
+
+    __attributes__: dict[str, tuple[type, ParamInfo]] = {}
+
+    def __init_subclass__(cls, **kwargs):
+        """
+        Inspect annotated attributes on the subclass and build a mapping
+        of parameter definitions for OpenAI schema generation.
+        """
+        super().__init_subclass__(**kwargs)
+        cls.__attributes__ = {}
+        for name, type_ in get_type_hints(cls).items():
+            default = cls.__dict__.get(name, None)
+            if isinstance(default, ParamInfo):
+                cls.__attributes__[name] = (type_, default)
+            elif default is not None:
+                cls.__attributes__[name] = (type_, ParamInfo(default=default))
+            else:
+                cls.__attributes__[name] = (type_, ParamInfo())
+
+    def __init__(self, **kwargs):
+        """
+        Instantiate a Param subclass by validating and assigning each
+        annotated field, falling back to class-level defaults if absent.
+
+        Raises:
+            TypeError: if a provided value does not match the annotated type,
+                       or if unexpected fields are passed.
+        """
+        cls = type(self)
+        hints = get_type_hints(cls)
+
+        # Assign annotated fields
+        for name, typ in hints.items():
+            if name in kwargs:
+                value = kwargs.pop(name)
+                # simple type check
+                if not isinstance(value, typ) and value is not None:
+                    raise TypeError(f"Field '{name}' expected {typ}, got {type(value)}")
+                setattr(self, name, value)
+            else:
+                # use class‐level default if given, else None
+                attr = getattr(cls, name, None)
+                if isinstance(attr, ParamInfo):
+                    default = attr.default
+                else:
+                    default = attr
+                setattr(self, name, default)
+
+        if kwargs:
+            unexpected = ", ".join(kwargs)
+            raise TypeError(f"Unexpected fields for {cls.__name__}: {unexpected}")
+
+    def __repr__(self):
+        vals = ", ".join(f"{k}={v!r}" for k, v in self.dict().items())
+        return f"{type(self).__name__}({vals})"
+
+    @classmethod
+    def to_openai(cls, context: _AgentContext) -> List[Dict[str, Any]]:
+        """
+        Generate a JSON-schema-style dictionary suitable for OpenAI function
+        parameter definitions.
+
+        Returns:
+            Dict[str, Any]: A schema object with keys:
+              - "type": always "object"
+              - "properties": mapping from field names to their OpenAI types
+              - "required": list of names marked as required
+        """
+        properties: Dict[str, dict] = defaultdict(dict)
+        required = []
+
+        for name, (type_, info) in cls.__attributes__.items():
+            resolved_info = info.resolve(context)
+            properties[name]["type"] = _TYPE_MAP.get(type_, "string")
+            if resolved_info.description:
+                properties[name]["description"] = resolved_info.description
+            if resolved_info.values:
+                properties[name]["enum"] = resolved_info.values
+
+            if resolved_info.required:
+                required.append(name)
+
+        return {"type": "object", "properties": dict(properties), "required": required}

pyagentic/_base/_resolver.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass, fields, replace
+from typing import Annotated, TypeVar, get_origin, get_args, Any, Self
+
+from typeguard import check_type, TypeCheckError
+
+from pyagentic._base._context import _AgentContext, ContextRef
+from pyagentic._base._exceptions import InvalidContextRefMismatchTyping
+
+
+class _CtxMarker:
+    pass
+
+
+T = TypeVar("T")
+MaybeContext = Annotated[T, _CtxMarker()]
+
+
+@dataclass
+class ContextualMixin:
+    """
+    Class to be extended if any of the properties in the class may use a `ContextRef`. Gives the
+    subclass access to `resolve`, which allows a context to be passed in to backfill any
+    context-ready properties
+    """
+
+    def resolve(self, ctx: _AgentContext) -> Self:
+        updates: dict[str, Any] = {}
+        for f in fields(self):
+            tp = f.type
+            # only look at Annotated[...] with our marker
+            if get_origin(tp) is Annotated and any(
+                isinstance(m, _CtxMarker) for m in get_args(tp)[1:]
+            ):
+
+                raw = getattr(self, f.name)
+                if isinstance(raw, ContextRef):
+                    value = ctx.get(raw.path)
+                    # expected type is the first Annotated arg
+                    expected_type = get_args(tp)[0]
+                    try:
+                        check_type(value, expected_type)
+                    except TypeCheckError:
+                        raise InvalidContextRefMismatchTyping(
+                            ref_path=raw.path,
+                            field_name=f.name,
+                            recieved_type=type(value),
+                            expected_type=expected_type,
+                        )
+                    updates[f.name] = value
+                    # return a new instance with those fields replaced
+        return replace(self, **updates)

pyagentic/_base/_tool.py

@@ -0,0 +1,154 @@
+import inspect
+from typing import Callable, Any, TypeVar, get_type_hints
+from collections import defaultdict
+
+from pyagentic._base._params import Param, ParamInfo, _TYPE_MAP
+from pyagentic._base._context import _AgentContext
+from pyagentic._base._exceptions import ToolDeclarationFailed
+
+
+class _ToolDefinition:
+    """
+    Private class to handle tool definitions
+
+    Attributes:
+        name(str): Name of the tool, automatically filled out as the function name
+        description(str): Description of the tool for LLM to read
+        parameters(str): Dictionary containing parameters captured by the tool descriptor
+        condition(str): The condition supplied determining when this tool should be included
+            in the LLM inference call
+
+    Methods:
+        to_openai()->dict: Converts the definition to an "openai-ready" dictionary
+        compile_args()->dict[str, Any]: Converts any raw kwargs, usually from LLM tool call, to
+            match that of the tool definition. This process does the following:
+                1. Fills in any default values for args not supplied
+                2. Casts a raw dictionary to any arg that is a Param class
+    """
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        parameters: dict[str, tuple[TypeVar, ParamInfo]],
+        condition: Callable[[Any], bool] = None,
+    ):
+        self.name: str = name
+        self.description: str = description
+        self.parameters: dict[str, tuple[TypeVar, ParamInfo]] = parameters
+        self.condition = condition
+
+    def to_openai(self, context: _AgentContext) -> dict:
+        """
+        Converts the definition to an "openai-ready" dictionary
+
+        Returns:
+            dict: A openai dictionary for tool calling
+        """
+        params = defaultdict(dict)
+        required = []
+
+        for name, attr in self.parameters.items():
+            type_, default = attr
+
+            if issubclass(type_, Param):
+                params[name] = type_.to_openai(context)
+            else:
+                params[name] = {"type": _TYPE_MAP.get(type_, "string")}
+            if isinstance(default, ParamInfo):
+                resolved_default = default.resolve(context)
+                if resolved_default.description:
+                    params[name]["description"] = resolved_default.description
+                if resolved_default.required:
+                    required.append(name)
+                if resolved_default.values:
+                    params[name]["enum"] = resolved_default.values
+
+        return {
+            "type": "function",
+            "name": self.name,
+            "description": self.description,
+            "parameters": {"type": "object", "properties": dict(params)},
+            "required": required,
+        }
+
+    def compile_args(self, **kwargs) -> dict[str, Any]:
+        """
+        Converts the definition to an "openai-ready" dictionary
+        compile_args()->dict[str, Any]: Converts any raw kwargs, usually from LLM tool call, to
+            match that of the tool definition. This process does the following:
+                1. Fills in any default values for args not supplied
+                2. Casts a raw dictionary to any arg that is a Param class
+
+        Args:
+            **kwargs: Recieves any arguements that will be verified and compiled
+
+        Returns:
+            dict[str, Any]: Dictionary of args that are ready to be run through the tool
+        """
+        compiled_args = {}
+
+        for name, (type_, info) in self.parameters.items():
+            if name in kwargs:
+                if issubclass(type_, Param):
+                    param_args = kwargs[name]
+                    compiled_args[name] = type_(**param_args)
+                else:
+                    compiled_args[name] = kwargs[name]
+            else:
+                compiled_args[name] = info.default
+
+        return compiled_args
+
+
+def tool(
+    description: str,
+    condition: Callable[[Any], bool] = None,
+):
+    """
+    Decorator to mark a method as a callable tool.
+    All methods marked with this descriptor **must** return a string
+
+    Args:
+        description(str): Description of the tool that will be read by the LLM
+        condition(Callable): A callable that returns a boolean, determining when the tool
+            will be included in the LLM inference call
+    """
+
+    def decorator(fn: Callable):
+        # Check return type
+        types = get_type_hints(fn)
+        return_type = types.pop("return", None)
+        if return_type != str:
+            raise ToolDeclarationFailed(
+                tool_name=fn.__name__, message="Method must have a return type of `str`"
+            )
+
+        # 2) grab default values
+        sig = inspect.signature(fn)
+        defaults = {
+            param_name: param.default
+            for param_name, param in sig.parameters.items()
+            if param.default is not inspect._empty
+        }
+
+        params = {}
+
+        for name, type_ in types.items():
+            default = defaults.get(name, None)
+            if isinstance(default, ParamInfo):
+                params[name] = (type_, default)
+            elif default is not None:
+                params[name] = (type_, ParamInfo(default=default))
+            else:
+                params[name] = (type_, ParamInfo())
+
+        fn.__tool_def__ = _ToolDefinition(
+            name=fn.__name__,
+            description=description or fn.__doc__ or "",
+            parameters=params,
+            condition=condition,
+        )
+        return fn
+
+    return decorator

pyagentic/logging.py

@@ -0,0 +1,53 @@
+import logging
+from logging.config import dictConfig
+
+LOG_LEVEL = "WARNING"
+
+LOGGING_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "colored": {
+            "()": "colorlog.ColoredFormatter",
+            "format": (
+                "%(log_color)s[%(asctime)s]%(reset)s "
+                "%(log_color)s%(levelname)-8s%(reset)s - "
+                "%(name)s - %(message)s"
+            ),
+            "log_colors": {
+                "DEBUG": "cyan",
+                "INFO": "green",
+                "WARNING": "yellow",
+                "ERROR": "red",
+                "CRITICAL": "bold_red",
+            },
+            "reset": True,
+        },
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "colored",
+            "level": LOG_LEVEL,
+            "stream": "ext://sys.stdout",
+        },
+    },
+    "root": {
+        "handlers": ["console"],
+        "level": LOG_LEVEL,
+    },
+}
+
+_configured = False
+
+
+def configure_logging() -> None:
+    global _configured
+    if not _configured:
+        dictConfig(LOGGING_CONFIG)
+        _configured = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    configure_logging()
+    return logging.getLogger(name)

pyagentic/updates.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel
+from typing import Literal
+from enum import Enum
+
+
+class Status(Enum):
+    GENERATING = "generating"
+    PROCESSING = "processing"
+    SUCCEDED = "succeded"
+    ERROR = "error"
+
+
+class EmitUpdate(BaseModel):
+    type: Literal["base"] = "base"
+    status: Status
+
+
+class AiUpdate(EmitUpdate):
+    type: Literal["ai_response"] = "ai_response"
+    message: str = None
+
+
+class ToolUpdate(EmitUpdate):
+    type: Literal["tool_update"] = "tool_update"
+    tool_call: str = None
+    tool_args: dict = None

pyagentic_core-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+pyagentic/__init__.py,sha256=HK0W-YC66O4elkka_oUpWKRMCi0a5O3B9i4eT-zM534,312
+pyagentic/logging.py,sha256=cyxD_FLZaLRX0tvEkIEhfhLozTxn2TR_JPVTf8UzgcI,1266
+pyagentic/updates.py,sha256=O-3b2SIiWYYD3aAn7mLfxo-lYVNoNxA9LopmYFgwIqQ,530
+pyagentic/_base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyagentic/_base/_agent.py,sha256=IH5OvaWHz_NqkDU9bDP2cXnqVmrdST9X6Vs7RppLw3I,6895
+pyagentic/_base/_context.py,sha256=nAyilVB3RH3bG32GKGwTfABgs7d_9RHQ8pYTkGnOi4g,7491
+pyagentic/_base/_exceptions.py,sha256=okLcEx5ml68IbfC5rbaPTxTmkwa5pDdpIsmC27HqXr0,1321
+pyagentic/_base/_metaclasses.py,sha256=04RQLea6T2RUuVj_ef8tEGDH-TdTVoAKPNERK-YTJo8,6201
+pyagentic/_base/_params.py,sha256=LoMhfzZV5Y6A54zkzAvhVpO5AffRbvr_P6TOzrxjqO4,5096
+pyagentic/_base/_resolver.py,sha256=C25_u6JFO4CXpLMWI9ooyUwE9WrpYvu_eeZMo65IW2U,1831
+pyagentic/_base/_tool.py,sha256=nu5OrzglQLyZgo7lWmxSGJyUyMnRWLTVt0YTm_8fILM,5546
+pyagentic_core-1.0.0.dist-info/licenses/LICENSE,sha256=wcOzTj82hOc96HztJk2VzLB2hFHpdIGpjz8vvbpP1_s,1069
+pyagentic_core-1.0.0.dist-info/METADATA,sha256=MngTyhX15ucwi8_2TS7Xnhu6fzZBYCBLLYX538SDbX4,3742
+pyagentic_core-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyagentic_core-1.0.0.dist-info/top_level.txt,sha256=lAWfd-ay434uEpSg2FM0ySN0o4vgNGE6D9dJkIhGyfY,10
+pyagentic_core-1.0.0.dist-info/RECORD,,

pyagentic_core-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyagentic_core-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyagentic