pyagentic-core 2.0.0b1__tar.gz

pyagentic_core-2.0.0b1/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-2.0.0b1/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: pyagentic-core
+Version: 2.0.0b1
+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: dotenv>=0.9.9
+Requires-Dist: ipykernel>=6.29.5
+Requires-Dist: taskipy>=1.14.1
+Requires-Dist: openai>=1.99.3
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: typeguard>=4.4.4
+Requires-Dist: c3linearize>=0.1.0
+Requires-Dist: anthropic>=0.62.0
+Requires-Dist: google-generativeai>=0.8.0
+Dynamic: license-file
+
+# PyAgentic
+
+[![Python Version](https://img.shields.io/badge/python-3.13%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, type-safe framework for building AI agents with OpenAI integration. PyAgentic lets you create sophisticated LLM agents using clean Python class syntax, with full support for tools, persistent state, agent linking, and agent inheritance.
+
+## Documentation
+
+Read the **[Getting Started](https://rmikulec.github.io/pyAgentic/getting-started/)**!
+
+Complete documentation, tutorials, and examples can be found **[here](https://rmikulec.github.io/pyagentic)**
+
+## Features
+
+- **Declarative Design** - Define agents with simple class-based syntax and decorators
+- **Powerful Tools** - Easy `@tool` decoration with automatic OpenAI schema generation
+- **Persistent State** - Stateful agents with `State` fields that persist across conversations
+- **Agent Linking** - Compose complex workflows by linking agents together
+- **Structured Responses** - Type-safe Pydantic responses with full tool execution details
+- **Dynamic Constraints** - Use `ref` to create smart parameter validation
+- **Inheritance & Extensions** - Build agent hierarchies and mix in cross-cutting capabilities
+- **Native Async Support** - Built for scalable applications with async/await throughout
+- **Type Safety** - Complete typing support with validation and IDE autocompletion
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install pyagentic-core
+```
+
+### Simple Agent Example
+
+```python
+from pyagentic import BaseAgent, tool, State, spec
+
+class ResearchAgent(BaseAgent):
+    __system_message__ = "I help with research tasks and maintain a collection of papers"
+
+    # Persistent state that survives across conversations
+    paper_count: State[int] = spec.State(default=0)
+    current_topic: State[str] = spec.State(default="general", access="write")
+
+    @tool("Search for academic papers")
+    def search_papers(self, query: str, max_results: int = 5) -> str:
+        # Your search logic here
+        self.paper_count += max_results
+        return f"Found {max_results} papers about '{query}'"
+
+# Create and use the agent
+agent = ResearchAgent(model="openai::gpt-4", api_key="your-key")
+response = await agent("Help me research machine learning papers")
+
+# Access structured response data
+print(response.final_output)  # Natural language response
+print(len(response.tool_responses))  # Number of tools called
+print(agent.paper_count)  # Persistent state
+```
+
+### Advanced Features
+
+#### Agent Linking
+Create multi-agent workflows where agents can call other agents as tools:
+
+```python
+class DatabaseAgent(BaseAgent):
+    __system_message__ = "I query databases"
+    __description__ = "Retrieves data from SQL databases"
+
+    @tool("Execute SQL query")
+    def query(self, sql: str) -> str: ...
+
+class WebAgent(BaseAgent):
+    __system_message__ = "I search the web"
+    __description__ = "Searches the internet"
+
+    @tool("search")
+    def search(self, terms: list[str]) -> str: ...
+
+class ReportAgent(BaseAgent):
+    __system_message__ = "I generate business reports"
+    database: DatabaseAgent  # Linked agent appears as a tool
+    searcher: WebAgent
+
+    @tool("Create visualization")
+    def create_chart(self, data: str) -> str: ...
+
+# The report agent can automatically coordinate with the database agent
+report_agent = ReportAgent(database=DatabaseAgent(...), searcher=WebAgent(...))
+response = await report_agent("Generate a plot of the latest financial data")
+```
+
+#### Dynamic Parameter Constraints
+Use `ref` with Pydantic computed fields to create intelligent parameter validation:
+
+```python
+from pydantic import BaseModel, computed_field
+from pyagentic import ref, spec
+
+class DatasetState(BaseModel):
+    available_datasets: list = []
+
+    @computed_field
+    @property
+    def dataset_names(self) -> list[str]:
+        return [ds['name'] for ds in self.available_datasets]
+
+class DataAgent(BaseAgent):
+    __system_message__ = "I manage datasets"
+
+    datasets: State[DatasetState] = spec.State(default_factory=DatasetState)
+
+    @tool("Analyze specific dataset")
+    def analyze(
+        self,
+        dataset: str = spec.Param(
+            description="Dataset to analyze",
+            values=ref.datasets.dataset_names  # LLM can only pick from available datasets
+    )) -> str: ...
+```
+
+## Contributing
+
+Contribution is welcome! Whether it's bug fixes, new features, documentation improvements, or examples, help is appreciated.
+
+### Development Setup
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/your-username/pyagentic.git
+   cd pyagentic
+   ```
+
+2. **Install dependencies with uv**
+   ```bash
+   # Install uv if you haven't already
+   pip install uv
+   
+   # Install all dependencies including dev tools
+   uv sync --group dev
+   ```
+
+### Code Quality
+
+Several tools are used to maintain code quality:
+
+#### Formatting with Black
+```bash
+# Format all Python files
+uv run black -l99 pyagentic tests
+
+# Check formatting without making changes
+uv run black -l99 --check pyagentic tests
+```
+
+#### Linting with Flake8
+```bash
+# Run linting checks
+uv run flake8 --max-line-length=99 pyagentic tests 
+```
+
+
+### Testing
+
+```bash
+# Run all tests
+uv run pytest tests
+
+# Run tests with coverage
+uv run coverage run -m pytest tests
+```
+
+### Documentation
+
+Documentation is built with MkDocs and deployed automatically:
+
+#### Local Development
+```bash
+# Install docs dependencies
+uv sync --group docs
+
+# Serve docs locally (auto-reloads on changes)
+uv run task serve-docs
+
+# Build docs to ./site/
+uv run task build-docs
+```
+
+Docs are automatically deployed on pushes to main via GitHub Actions.
+
+### Submitting Changes
+
+1. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following the code style guidelines
+
+3. **Run the full test suite**
+   ```bash
+   uv run black pyagentic tests
+   uv run flake8 pyagentic tests --max-line-length=99
+   uv run pytest
+   ```
+
+4. **Commit with conventional commit messages**
+   ```bash
+   git commit -m "feat: add new agent linking feature"
+   git commit -m "fix: resolve context persistence issue"
+   git commit -m "docs: improve getting started guide"
+   ```
+
+5. **Push and create a Pull Request**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+### Conventional Commits
+
+Conventional commits are used for automatic versioning:
+
+- `feat:` - New features (minor version bump)
+- `fix:` - Bug fixes (patch version bump)
+- `docs:` - Documentation changes
+- `test:` - Test additions or improvements
+- `refactor:` - Code refactoring
+- `style:` - Code style changes (formatting, etc.)
+
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pyagentic_core-2.0.0b1/README.md

@@ -0,0 +1,237 @@
+# PyAgentic
+
+[![Python Version](https://img.shields.io/badge/python-3.13%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, type-safe framework for building AI agents with OpenAI integration. PyAgentic lets you create sophisticated LLM agents using clean Python class syntax, with full support for tools, persistent state, agent linking, and agent inheritance.
+
+## Documentation
+
+Read the **[Getting Started](https://rmikulec.github.io/pyAgentic/getting-started/)**!
+
+Complete documentation, tutorials, and examples can be found **[here](https://rmikulec.github.io/pyagentic)**
+
+## Features
+
+- **Declarative Design** - Define agents with simple class-based syntax and decorators
+- **Powerful Tools** - Easy `@tool` decoration with automatic OpenAI schema generation
+- **Persistent State** - Stateful agents with `State` fields that persist across conversations
+- **Agent Linking** - Compose complex workflows by linking agents together
+- **Structured Responses** - Type-safe Pydantic responses with full tool execution details
+- **Dynamic Constraints** - Use `ref` to create smart parameter validation
+- **Inheritance & Extensions** - Build agent hierarchies and mix in cross-cutting capabilities
+- **Native Async Support** - Built for scalable applications with async/await throughout
+- **Type Safety** - Complete typing support with validation and IDE autocompletion
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install pyagentic-core
+```
+
+### Simple Agent Example
+
+```python
+from pyagentic import BaseAgent, tool, State, spec
+
+class ResearchAgent(BaseAgent):
+    __system_message__ = "I help with research tasks and maintain a collection of papers"
+
+    # Persistent state that survives across conversations
+    paper_count: State[int] = spec.State(default=0)
+    current_topic: State[str] = spec.State(default="general", access="write")
+
+    @tool("Search for academic papers")
+    def search_papers(self, query: str, max_results: int = 5) -> str:
+        # Your search logic here
+        self.paper_count += max_results
+        return f"Found {max_results} papers about '{query}'"
+
+# Create and use the agent
+agent = ResearchAgent(model="openai::gpt-4", api_key="your-key")
+response = await agent("Help me research machine learning papers")
+
+# Access structured response data
+print(response.final_output)  # Natural language response
+print(len(response.tool_responses))  # Number of tools called
+print(agent.paper_count)  # Persistent state
+```
+
+### Advanced Features
+
+#### Agent Linking
+Create multi-agent workflows where agents can call other agents as tools:
+
+```python
+class DatabaseAgent(BaseAgent):
+    __system_message__ = "I query databases"
+    __description__ = "Retrieves data from SQL databases"
+
+    @tool("Execute SQL query")
+    def query(self, sql: str) -> str: ...
+
+class WebAgent(BaseAgent):
+    __system_message__ = "I search the web"
+    __description__ = "Searches the internet"
+
+    @tool("search")
+    def search(self, terms: list[str]) -> str: ...
+
+class ReportAgent(BaseAgent):
+    __system_message__ = "I generate business reports"
+    database: DatabaseAgent  # Linked agent appears as a tool
+    searcher: WebAgent
+
+    @tool("Create visualization")
+    def create_chart(self, data: str) -> str: ...
+
+# The report agent can automatically coordinate with the database agent
+report_agent = ReportAgent(database=DatabaseAgent(...), searcher=WebAgent(...))
+response = await report_agent("Generate a plot of the latest financial data")
+```
+
+#### Dynamic Parameter Constraints
+Use `ref` with Pydantic computed fields to create intelligent parameter validation:
+
+```python
+from pydantic import BaseModel, computed_field
+from pyagentic import ref, spec
+
+class DatasetState(BaseModel):
+    available_datasets: list = []
+
+    @computed_field
+    @property
+    def dataset_names(self) -> list[str]:
+        return [ds['name'] for ds in self.available_datasets]
+
+class DataAgent(BaseAgent):
+    __system_message__ = "I manage datasets"
+
+    datasets: State[DatasetState] = spec.State(default_factory=DatasetState)
+
+    @tool("Analyze specific dataset")
+    def analyze(
+        self,
+        dataset: str = spec.Param(
+            description="Dataset to analyze",
+            values=ref.datasets.dataset_names  # LLM can only pick from available datasets
+    )) -> str: ...
+```
+
+## Contributing
+
+Contribution is welcome! Whether it's bug fixes, new features, documentation improvements, or examples, help is appreciated.
+
+### Development Setup
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/your-username/pyagentic.git
+   cd pyagentic
+   ```
+
+2. **Install dependencies with uv**
+   ```bash
+   # Install uv if you haven't already
+   pip install uv
+   
+   # Install all dependencies including dev tools
+   uv sync --group dev
+   ```
+
+### Code Quality
+
+Several tools are used to maintain code quality:
+
+#### Formatting with Black
+```bash
+# Format all Python files
+uv run black -l99 pyagentic tests
+
+# Check formatting without making changes
+uv run black -l99 --check pyagentic tests
+```
+
+#### Linting with Flake8
+```bash
+# Run linting checks
+uv run flake8 --max-line-length=99 pyagentic tests 
+```
+
+
+### Testing
+
+```bash
+# Run all tests
+uv run pytest tests
+
+# Run tests with coverage
+uv run coverage run -m pytest tests
+```
+
+### Documentation
+
+Documentation is built with MkDocs and deployed automatically:
+
+#### Local Development
+```bash
+# Install docs dependencies
+uv sync --group docs
+
+# Serve docs locally (auto-reloads on changes)
+uv run task serve-docs
+
+# Build docs to ./site/
+uv run task build-docs
+```
+
+Docs are automatically deployed on pushes to main via GitHub Actions.
+
+### Submitting Changes
+
+1. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following the code style guidelines
+
+3. **Run the full test suite**
+   ```bash
+   uv run black pyagentic tests
+   uv run flake8 pyagentic tests --max-line-length=99
+   uv run pytest
+   ```
+
+4. **Commit with conventional commit messages**
+   ```bash
+   git commit -m "feat: add new agent linking feature"
+   git commit -m "fix: resolve context persistence issue"
+   git commit -m "docs: improve getting started guide"
+   ```
+
+5. **Push and create a Pull Request**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+### Conventional Commits
+
+Conventional commits are used for automatic versioning:
+
+- `feat:` - New features (minor version bump)
+- `fix:` - Bug fixes (patch version bump)
+- `docs:` - Documentation changes
+- `test:` - Test additions or improvements
+- `refactor:` - Code refactoring
+- `style:` - Code style changes (formatting, etc.)
+
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pyagentic_core-2.0.0b1/pyagentic/__init__.py

@@ -0,0 +1,46 @@
+"""
+PyAgentic: A declarative framework for building LLM-powered agents.
+
+PyAgentic provides a clean, type-safe way to build agentic systems with:
+  - Tool calling: Let LLMs invoke Python functions
+  - Stateful agents: Maintain conversation and application state
+  - Multi-agent systems: Link agents together for complex workflows
+  - Provider flexibility: Support for OpenAI, Anthropic, and custom providers
+  - Observability: Built-in tracing with BasicTracer and LangfuseTracer
+
+Quick Start:
+    ```python
+    from pyagentic import BaseAgent, tool
+
+    class MyAgent(BaseAgent):
+        __system_message__ = "You are a helpful assistant"
+
+        @tool("Calculate the sum of two numbers")
+        def add(self, a: int, b: int) -> str:
+            return str(a + b)
+
+    # Create and run the agent
+    agent = MyAgent(model="openai::gpt-4o", api_key="your-key")
+    response = await agent.run("What is 5 + 3?")
+    print(response.final_output)  # The LLM will call the add tool
+    ```
+
+Main Components:
+    - BaseAgent: Base class for defining agents
+    - tool: Decorator for marking methods as LLM-callable tools
+    - State: Type annotation for persistent state fields
+    - Link: Type annotation for linking agents together
+    - spec: Configuration factory for state, params, and agent links
+    - ref: Dynamic state reference system for tool parameters
+    - AgentExtension: Base class for creating reusable agent mixins
+"""
+
+from pyagentic._base._spec import spec
+from pyagentic._base._agent._agent import BaseAgent, AgentExtension
+from pyagentic._base._agent._agent_linking import Link
+from pyagentic._base._tool import tool
+
+from pyagentic._base._state import State
+from pyagentic._base._ref import ref
+
+__all__ = ["BaseAgent", "AgentExtension", "tool", "spec", "State", "Link", "ref"]