Metadata-Version: 2.4
Name: autourgos-agent-utils
Version: 0.1.0
Summary: Shared utilities for Autourgos agents — colored logger, tool executor, and history tracking.
Author-email: DevxJitin <devxjitin@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/autourgoskit/autourgos-agent-utils
Project-URL: Repository, https://github.com/autourgoskit/autourgos-agent-utils
Project-URL: Issues, https://github.com/autourgoskit/autourgos-agent-utils/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: autourgos-core>=0.1.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 Agent Utils</h1>
  <p><em>Essential, reusable utilities for building and managing AI agents in the Autourgos ecosystem.</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.10%2B-blue.svg?style=flat-square&logo=python)](https://www.python.org/)
</div>

---

Welcome to the **`autourgos-agent-utils`** package. This library provides comprehensive, high-performance utilities for colored console logging, dynamic tool execution, structured conversation history tracking, and managing context-windowed scratchpads.

Built to simplify agent infrastructure, it abstracts away the complex boilerplate of tool invocation and state tracking so you can focus on building intelligent agent logic.

---

## Table of Contents
1. [Installation](#installation)
2. [Agent Logging](#agent-logging)
3. [Tool Execution](#tool-execution)
4. [Memory & History](#memory--history)
   - [AgentHistoryLogger](#agenthistorylogger)
5. [Helper Functions](#helper-functions)

---

## Installation

Install the utility package using pip:

```bash
pip install autourgos-agent-utils
```

> **Note:** This package depends on `autourgos-core >= 0.1.0`.

---

## Agent Logging

**`AgentLogger`** provides enhanced, colored console logging tailored specifically for agent workflows (Thoughts, Actions, Observations, Final Answers).

```python
from autourgos_agent_utils import create_logger

# Initialize a colored logger for a specific agent
logger = create_logger("MyAgent")

logger.info("Agent initialized successfully.")
logger.warning("Approaching token limits.")
```

---

## Tool Execution

Robust dynamic tool execution components (**`Tool_Executor`** and **`AsyncTool_Executor`**) safely invoke external functions and tools, automatically handling parameter injection and error recovery.

```python
from autourgos_agent_utils import Tool_Executor, register_tool

@register_tool
def get_weather(location: str) -> str:
    """Fetches the weather for a given location."""
    return f"The weather in {location} is sunny."

tools = [get_weather]
executor = Tool_Executor(tools)

# Dynamically execute a tool by name with dictionary arguments
result = executor.execute("get_weather", {"location": "London"})
print(result) # Output: The weather in London is sunny.
```

---

## Memory & History

### AgentHistoryLogger
Keep track of conversational trails and reasoning steps with markdown-based history export.

```python
from autourgos_agent_utils import AgentHistoryLogger

history = AgentHistoryLogger(agent_name="ResearchBot", enabled=True)
history.start_task("I need to find the latest documentation.")
history.log_iteration(
    iteration_num=1,
    thought="I should search for the latest documentation.",
    tools=[{"tool": "search_web", "params": {"query": "autourgos docs"}}],
    observations=[{"tool": "search_web", "result": "Found 5 documents."}]
)
history.log_final("Here are the latest docs.")
```

---

## Helper Functions

The package exposes various utility functions for common agent tasks:

- **`parse_json_object`**: Safely extracts and parses JSON strings embedded deep within raw LLM text responses.
- **`check_timeout`**: Evaluates elapsed execution time against configured limits.
- **`escape_prompt_braces`**: Prevents `KeyError` exceptions when utilizing `.format()` on prompts containing raw JSON structures.

---

<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>
