Metadata-Version: 2.4
Name: autourgos-core
Version: 0.1.1
Summary: Core tool system for the Autourgos agentic AI framework — Tool class, @tool decorator, and schema generation.
Author-email: DevxJitin <devxjitin@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/autourgoskit/autourgos-core
Project-URL: Repository, https://github.com/autourgoskit/autourgos-core
Project-URL: Issues, https://github.com/autourgoskit/autourgos-core/issues
Keywords: ai,llm,agents,agentic-ai,autourgos,genai,autonomous-agents,prompt-engineering,rag,tool-calling,machine-learning,nlp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"

<div align="center">
  <img src="./assets/logo.png" alt="Autourgos Logo" width="300">
  <h1>Autourgos Core</h1>
  <p><em>The foundational abstractions and robust toolkit for building autonomous agents.</em></p>

  [![Developed by DevxJitin](https://img.shields.io/badge/Developed%20by-DevxJitin-0e76a8?style=flat-square&logo=github)](https://github.com/DevxJitin) [![Documented by Sonia](https://img.shields.io/badge/Documented%20by-Sonia-10b981?style=flat-square&logo=github)](https://github.com/SoniaDahiya) [![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg?style=flat-square&logo=python)](https://www.python.org/)
</div>

---

Welcome to the **`autourgos-core`** package. This library provides the baseline abstractions for building, configuring, and extending agents and their toolsets. 

Built with developer experience in mind, it strips away heavy boilerplate, allowing you to focus purely on agent orchestration, type-safe tool execution, and lifecycle management.

---

## Table of Contents
1. [Installation](#installation)
2. [Tools & Actions](#tools--actions)
   - [The `@tool` Decorator](#the-tool-decorator)
   - [Manual Instantiation](#manual-instantiation)
   - [Pydantic Validation](#pydantic-validation)
   - [Human-in-the-Loop](#human-in-the-loop)
3. [Tool Results](#tool-results)
4. [BaseAgent Abstraction](#baseagent-abstraction)
5. [Lifecycle Callbacks](#lifecycle-callbacks)
6. [Lifecycle Callbacks](#lifecycle-callbacks)

---

## Installation

Install the core package using pip:

```bash
pip install autourgos-core
```

---

## Tools & Actions

A **Tool** represents an actionable function that an agent can execute. `autourgos-core` provides highly flexible ways to define them.

### The `@tool` Decorator
The simplest and most pythonic way to create a tool is by decorating a strongly-typed function. Type hints and docstrings are automatically parsed into the tool's schema.

```python
from autourgos.core import tool

@tool
def get_weather(location: str) -> str:
    """
    Retrieves the weather for a specific location.
    
    Args:
        location (str): The location to lookup (e.g., 'Paris')
    """
    return f"The weather in {location} is 75°F"

print(get_weather.name)         # Output: 'get_weather'
print(get_weather.description)  # Output: 'Retrieves the weather...'
```

### Manual Instantiation
If you prefer not to use decorators or need to generate tools dynamically at runtime, you can instantiate the `Tool` class directly.

```python
from autourgos.core import Tool

def multiply(a: int, b: int) -> int:
    return a * b

calculator_tool = Tool(
    name="calculator",
    description="Multiplies two integers",
    function=multiply,
    parameters={
        "a": {"type": "int", "description": "First number", "required": True},
        "b": {"type": "int", "description": "Second number", "required": True}
    }
)
```

### Pydantic Validation
For heavily structured or complex inputs, you can seamlessly use Pydantic `BaseModel` classes as parameters. `autourgos-core` natively understands them.

```python
from pydantic import BaseModel
from autourgos.core import tool

class FlightRequest(BaseModel):
    origin: str
    destination: str
    passengers: int

@tool
def book_flight(request: FlightRequest) -> str:
    """Books a flight using structured data."""
    return f"Booked {request.passengers} tickets to {request.destination}."
```

### Human-in-the-Loop
Tools that perform sensitive operations (like database drops or payments) can be flagged to require explicit human approval before execution.

```python
from autourgos.core import tool

@tool(requires_approval=True)
def delete_database(db_name: str) -> str:
    """Deletes a live database. Requires approval."""
    return f"Database {db_name} has been deleted."
```

### Third-Party Tool Support (LangChain)
`autourgos-core` is seamlessly compatible with third-party ecosystem tools. You can directly pass tools from frameworks like **LangChain**, LlamaIndex, or CrewAI—as long as they provide a readable `name`, `description`, and callable interface, Autourgos will natively wrap and parse them.

```python
from langchain.tools import DuckDuckGoSearchRun
from autourgos.core import Tool

# Use LangChain tools natively
search_tool = DuckDuckGoSearchRun()

# Autourgos agents and utilities can directly consume `search_tool`
```

---

## Tool Results

To ensure your agents handle tool execution outcomes properly—without resorting to fragile string manipulation—wrap your return values using the `ToolResult` interface.

```python
from autourgos.core import ToolResult, tool

@tool
def fetch_api_data(endpoint: str) -> ToolResult:
    """Fetches data from an external API."""
    if not endpoint:
        return ToolResult.fail("Endpoint is required.")
        
    try:
        # Simulate data fetch
        data = {"status": 200, "result": "Success"}
        return ToolResult.ok(data=data, latency_ms=120)
    except Exception as e:
        return ToolResult.fail(f"API request failed: {e}")
```

> **Pro Tip:** Using `ToolResult` allows agents to gracefully recover from `ToolResult.fail()` by adjusting their parameters and trying again.

---

## BaseAgent Abstraction

`BaseAgent` is the abstract base class for all Autourgos agents. It provides a robust, shared infrastructure for managing tools, callbacks, execution limits, and loops.

### Building a Custom Agent
When creating a custom agent, simply subclass `BaseAgent` and implement the required execution lifecycle methods.

```python
from autourgos.core import BaseAgent
from typing import Any

class MyCustomAgent(BaseAgent):
    def invoke(self, query: str, **kwargs: Any) -> str:
        # 1. Execute synchronous agent logic
        # 2. Prevent infinite loops/timeouts:
        #    if self._check_timeout(start_time): break
        return f"Agent processed: {query}"

    async def ainvoke(self, query: str, **kwargs: Any) -> str:
        # Asynchronous implementation
        return f"Agent async processed: {query}"

    def _parser(self, response: str) -> Any:
        # Parse the raw model response into actionable structures
        return {"action": "reply", "text": response}
```

---

## Lifecycle Callbacks

You can hook into events across the entire execution lifecycle using `CallbackHandler`. This is highly useful for logging, observability, tracing, or streaming outputs to a frontend.

```python
from autourgos.core import CallbackHandler
from typing import Any

class AuditLogger(CallbackHandler):
    def on_tool_start(self, tool_name: str, tool_input: dict, **kwargs) -> None:
        print(f"[START] Tool '{tool_name}' triggered with: {tool_input}")

    def on_tool_end(self, tool_name: str, tool_output: Any, **kwargs) -> None:
        print(f"[END] Tool '{tool_name}' completed. Result: {tool_output}")
```

---

<div align="center">
  <p>Made with ❤️ by <a href="https://github.com/DevxJitin">DevxJitin</a> and <a href="https://github.com/SoniaDahiya">Sonia</a></p>
</div>
