aixtools 0.1.0__tar.gz

aixtools-0.1.0/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: aixtools
+Version: 0.1.0
+Summary: Tools for AI exploration and debugging
+Requires-Python: >=3.11.2
+Description-Content-Type: text/markdown
+Requires-Dist: chainlit>=2.5.5
+Requires-Dist: colorlog>=6.9.0
+Requires-Dist: fasta2a>=0.5.0
+Requires-Dist: fastmcp>=2.10.2
+Requires-Dist: ipykernel>=6.29.5
+Requires-Dist: langchain-chroma>=0.2.3
+Requires-Dist: langchain-ollama>=0.3.2
+Requires-Dist: langchain-openai>=0.3.14
+Requires-Dist: mcp>=1.11.0
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pydantic-ai>=0.4.10
+Requires-Dist: pylint>=3.3.7
+Requires-Dist: rich>=14.0.0
+Requires-Dist: ruff>=0.11.6
+Requires-Dist: streamlit>=1.44.1
+Requires-Dist: watchdog>=6.0.0
+Provides-Extra: test
+Requires-Dist: pyyaml; extra == "test"
+Provides-Extra: feature
+Requires-Dist: logfire; extra == "feature"
+
+# AiXplore-tools
+
+AiXplore-tools (`axitools` for short) is a Python library to support AI agent development and debugging. It serves two main purposes:
+
+1. **Utility Library**: A collection of utility functions and classes for agent projects
+2. **Debugging Tool**: A Streamlit app (`log_view`) for visualizing and debugging agent applications by viewing messages logged by `ObjectLogger`
+
+
+## `.venv`
+
+```
+# Create a new environment
+uv venv .venv
+source .venv/bin/activate
+
+# Add packages
+uv add pydantic-ai
+uv add mcp[cli]
+uv add chainlit
+uv add streamlit
+
+# Add langchain
+uv add langchain-chroma
+uv add langchain-ollama
+uv add langchain-openai
+
+# Other packages
+uv add colorlog
+uv add pandas
+uv add rich
+uv add ruff
+uv add watchdog
+uv add ipykernel
+
+# Install this code as a package
+uv pip install -e .
+```
+
+## Installation
+
+Installing the package from GitHub, you can use `uv add` (prefered)
+```
+uv add https://github.com/your-org/aixtools.git
+```
+
+or using the `pip` commamnd
+```
+uv pip install https://github.com/your-org/aixtools.git
+```
+
+Remember to set up your [`.env` file](#environment-configuration).
+
+### Updating
+
+This package is in active development and changes often.
+
+You'll want to force uv to re-install or update it to the latest commit, even if the version hasn’t changed.
+
+```
+uv add --upgrade https://github.com/your-org/aixtools.git
+```
+
+### Example: Creatng a new project
+
+```
+# Create a new project
+uv init MyNewProject
+cd MyNewProject
+
+# Add a virtual environemnt and activate it
+uv venv .venv
+source .venv/bin/activate
+
+# Add this package
+uv add https://github.com/your-org/aixtools.git
+```
+
+### Environment Configuration
+
+AIXtools requires specific environment variables to be set for proper operation, especially when working with different model providers.
+
+Here is a [template of an `.env`](./.env_template) file you can use as reference.
+
+#### Setting Up Environment Variables
+
+1. Create a `.env` file in your project root based on the template below:
+
+```
+# Model family (azure, openai, or ollama)
+MODEL_FAMILY=azure
+VDB_EMBEDDINGS_MODEL_FAMILY=azure
+
+MODEL_TIMEOUT=120
+
+# Azure OpenAI
+AZURE_OPENAI_ENDPOINT=https://your_endpoint.openai.azure.com
+AZURE_OPENAI_API_VERSION=2024-06-01
+AZURE_OPENAI_API_KEY=your_secret_key
+AZURE_MODEL_NAME=gpt-4o
+AZURE_OPENAI_PROVIDER_ID=azure
+AZURE_VDB_EMBEDDINGS_MODEL_NAME=text-embedding-3-small
+
+# OpenAI
+OPENAI_MODEL_NAME=gpt-4.5-preview
+OPENAI_API_KEY=openai_api_key
+OPENAI_VDB_EMBEDDINGS_MODEL_NAME=text-embedding-3-small
+
+# Ollama models
+OLLAMA_MODEL_NAME=llama3.2:3b-instruct-fp16
+OLLAMA_LOCAL_URL=http://localhost:11434/v1
+OLLAMA_VDB_EMBEDDINGS_MODEL_NAME=snowflake-arctic-embed2:latest
+```
+
+2. Configure the variables according to your needs:
+   - Set `MODEL_FAMILY` to your preferred model provider (`azure`, `openai`, or `ollama`)
+   - Provide the appropriate API keys and endpoints for your chosen provider
+   - Adjust model names and timeouts as needed
+
+#### Important Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `MODEL_FAMILY` | The model provider to use (azure, openai, ollama) | Yes |
+| `MODEL_TIMEOUT` | Timeout in seconds for model requests | Yes |
+| `AZURE_*` | Azure OpenAI configuration (if using Azure) | If MODEL_FAMILY=azure |
+| `OPENAI_*` | OpenAI configuration (if using OpenAI) | If MODEL_FAMILY=openai |
+| `OLLAMA_*` | Ollama configuration (if using Ollama) | If MODEL_FAMILY=ollama |
+
+## Debugging tools: `log_view` and `ObjectLogger`
+
+The `ObjectLogger` provides a simple logging facility, these logs can then be visualized with `log_view` app.
+
+
+### `ObjectLogger`
+
+The `ObjectLogger` class allows you to log objects to a file for later analysis. This is particularly useful for debugging agent interactions.
+
+`ObjectLogger` simply serializes objects to a pickle file. It first removes unserializeable parts of the objects (e.g. like `async` managers).
+
+#### Basic Usage
+
+```python
+from aixtools.utils.log_objects import ObjectLogger
+
+# Create a logger as a context manager
+with ObjectLogger() as logger:
+    # Log any pickleable object
+    logger.log({"message": "Hello, world!"})
+    
+    # Log agent responses or any other objects
+    logger.log(agent_response)
+```
+
+#### Logging Agent Interactions
+
+The function `run_agent` logs each node from the agent run, roughtly it looks like this:
+
+```python
+async def run_agent(agent: Agent, prompt: str | list[str]):
+    nodes = []
+    async with agent.iter(prompt) as agent_run:
+        with ObjectLogger(debug=debug) as agent_logger:
+            async for node in agent_run:
+                agent_logger.log(node)
+                nodes.append(node)
+            result = agent_run.result
+    return result.data, nodes
+```
+
+#### Saving Multiple Objects
+
+```python
+from aixtools.utils.log_objects import save_objects_to_logfile
+
+# Save a list of objects to a log file
+objects = [obj1, obj2, obj3]
+save_objects_to_logfile(objects)
+```
+
+### log_view App
+
+The `log_view` app allows you to visualize and analyze the objects logged by `ObjectLogger`.
+
+It is a simple Streamlit app that you can run locally and view the log files.
+
+#### Running the App
+
+You can run the app using the command-line script installed with the package:
+
+```bash
+log_view
+```
+
+Or specify a custom log directory:
+
+```bash
+log_view /path/to/logs
+```
+
+#### Features
+
+The log_view app provides several features for analyzing logged objects:
+
+- **Log File Selection**: Choose from available log files
+- **Filtering**: Filter nodes by text, type, attributes, or regex patterns
+- **Visualization**: Expand/collapse nodes to view details
+- **Export**: Export filtered nodes to JSON
+
+#### Example Workflow
+
+1. Log agent interactions using `ObjectLogger`
+2. Run the `log_view` app to analyze the logs
+3. Filter and explore the logged objects
+4. Export interesting findings for further analysis
+
+## Additional Utilities
+
+AIXtools provides several other utilities to support agent development:
+
+### PersistedDict
+
+A dictionary that persists to a file on disk as JSON or pickle:
+
+```python
+from aixtools.utils.persisted_dict import PersistedDict
+
+# Create a persisted dictionary
+data = PersistedDict("data.json")
+
+# Use it like a regular dictionary
+data["key"] = "value"  # Automatically saved to disk
+```
+
+## Agent Utilities
+
+Functions for creating and running agents with different model providers:
+
+```python
+from aixtools.agents.agent import get_agent, run_agent
+
+# Create an agent with the default model (from MODEL_FAMILY)
+agent = get_agent(system_prompt="You are a helpful assistant.")
+
+# Create an agent with a specific model
+from aixtools.agents.agent import get_model_openai
+model = get_model_openai()
+agent = get_agent(system_prompt="You are a helpful assistant.", model=model)
+
+# Run the agent
+result, nodes = await run_agent(agent, "Tell me about AI")
+```
+
+### Batch Processing
+
+Run multiple agent queries simultaneously:
+
+```python
+from aixtools.agents.agent_batch import agent_batch, AgentQueryParams
+
+# Create query parameters
+query_parameters = [
+    AgentQueryParams(prompt="What is the meaning of life"),
+    AgentQueryParams(prompt="Who is the prime minister of Canada")
+]
+
+# Run queries in batches
+async for result in agent_batch(query_parameters):
+    print(result)
+```
+
+## Project Structure
+
+```
+aixtools/
+├── __init__.py           # Package initialization
+├── log_view.py           # Entry point for log_view app
+├── agents/               # Agent-related functionality
+│   ├── agent.py          # Core agent functions
+│   └── agent_batch.py    # Batch processing for agents
+├── log_view/             # Log viewer application
+│   ├── app.py            # Main Streamlit application
+│   ├── display.py        # Node display utilities
+│   ├── export.py         # Export functionality
+│   ├── filters.py        # Node filtering
+│   ├── log_utils.py      # Log file utilities
+│   └── node_utils.py     # Node processing utilities
+└── utils/                # Utility functions and classes
+    ├── config.py         # Configuration utilities
+    ├── log_objects.py    # Object logging functionality
+    ├── persisted_dict.py # Persistent dictionary
+    └── utils.py          # General utilities
+
+## Logging
+
+The logging system is configured using a standard Python `dictConfig` schema. By default, it will look for a `logging.yaml` or `logging.json` file in your project's root directory. You can also specify a custom path using the `LOGGING_CONFIG_PATH` environment variable.
+
+If no configuration file is found, a default colorized console logger will be used.
+
+### Example `logging.yaml`
+
+```yaml
+version: 1
+disable_existing_loggers: false
+formatters:
+  default:
+    format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+  color:
+    "()": "colorlog.ColoredFormatter"
+    "format": "%(log_color)s%(levelname)-8s%(reset)s [%(name)s] %(message)s"
+handlers:
+  console:
+    class: colorlog.StreamHandler
+    formatter: color
+    level: DEBUG
+  file:
+    class: logging.handlers.RotatingFileHandler
+    formatter: default
+    filename: app.log
+    maxBytes: 10485760 # 10MB
+    backupCount: 5
+    level: INFO
+root:
+  handlers: [console, file]
+  level: DEBUG
+loggers:
+  aixtools:
+    level: INFO
+```

aixtools-0.1.0/README.md

@@ -0,0 +1,328 @@
+# AiXplore-tools
+
+AiXplore-tools (`axitools` for short) is a Python library to support AI agent development and debugging. It serves two main purposes:
+
+1. **Utility Library**: A collection of utility functions and classes for agent projects
+2. **Debugging Tool**: A Streamlit app (`log_view`) for visualizing and debugging agent applications by viewing messages logged by `ObjectLogger`
+
+
+## `.venv`
+
+```
+# Create a new environment
+uv venv .venv
+source .venv/bin/activate
+
+# Add packages
+uv add pydantic-ai
+uv add mcp[cli]
+uv add chainlit
+uv add streamlit
+
+# Add langchain
+uv add langchain-chroma
+uv add langchain-ollama
+uv add langchain-openai
+
+# Other packages
+uv add colorlog
+uv add pandas
+uv add rich
+uv add ruff
+uv add watchdog
+uv add ipykernel
+
+# Install this code as a package
+uv pip install -e .
+```
+
+## Installation
+
+Installing the package from GitHub, you can use `uv add` (prefered)
+```
+uv add https://github.com/your-org/aixtools.git
+```
+
+or using the `pip` commamnd
+```
+uv pip install https://github.com/your-org/aixtools.git
+```
+
+Remember to set up your [`.env` file](#environment-configuration).
+
+### Updating
+
+This package is in active development and changes often.
+
+You'll want to force uv to re-install or update it to the latest commit, even if the version hasn’t changed.
+
+```
+uv add --upgrade https://github.com/your-org/aixtools.git
+```
+
+### Example: Creatng a new project
+
+```
+# Create a new project
+uv init MyNewProject
+cd MyNewProject
+
+# Add a virtual environemnt and activate it
+uv venv .venv
+source .venv/bin/activate
+
+# Add this package
+uv add https://github.com/your-org/aixtools.git
+```
+
+### Environment Configuration
+
+AIXtools requires specific environment variables to be set for proper operation, especially when working with different model providers.
+
+Here is a [template of an `.env`](./.env_template) file you can use as reference.
+
+#### Setting Up Environment Variables
+
+1. Create a `.env` file in your project root based on the template below:
+
+```
+# Model family (azure, openai, or ollama)
+MODEL_FAMILY=azure
+VDB_EMBEDDINGS_MODEL_FAMILY=azure
+
+MODEL_TIMEOUT=120
+
+# Azure OpenAI
+AZURE_OPENAI_ENDPOINT=https://your_endpoint.openai.azure.com
+AZURE_OPENAI_API_VERSION=2024-06-01
+AZURE_OPENAI_API_KEY=your_secret_key
+AZURE_MODEL_NAME=gpt-4o
+AZURE_OPENAI_PROVIDER_ID=azure
+AZURE_VDB_EMBEDDINGS_MODEL_NAME=text-embedding-3-small
+
+# OpenAI
+OPENAI_MODEL_NAME=gpt-4.5-preview
+OPENAI_API_KEY=openai_api_key
+OPENAI_VDB_EMBEDDINGS_MODEL_NAME=text-embedding-3-small
+
+# Ollama models
+OLLAMA_MODEL_NAME=llama3.2:3b-instruct-fp16
+OLLAMA_LOCAL_URL=http://localhost:11434/v1
+OLLAMA_VDB_EMBEDDINGS_MODEL_NAME=snowflake-arctic-embed2:latest
+```
+
+2. Configure the variables according to your needs:
+   - Set `MODEL_FAMILY` to your preferred model provider (`azure`, `openai`, or `ollama`)
+   - Provide the appropriate API keys and endpoints for your chosen provider
+   - Adjust model names and timeouts as needed
+
+#### Important Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `MODEL_FAMILY` | The model provider to use (azure, openai, ollama) | Yes |
+| `MODEL_TIMEOUT` | Timeout in seconds for model requests | Yes |
+| `AZURE_*` | Azure OpenAI configuration (if using Azure) | If MODEL_FAMILY=azure |
+| `OPENAI_*` | OpenAI configuration (if using OpenAI) | If MODEL_FAMILY=openai |
+| `OLLAMA_*` | Ollama configuration (if using Ollama) | If MODEL_FAMILY=ollama |
+
+## Debugging tools: `log_view` and `ObjectLogger`
+
+The `ObjectLogger` provides a simple logging facility, these logs can then be visualized with `log_view` app.
+
+
+### `ObjectLogger`
+
+The `ObjectLogger` class allows you to log objects to a file for later analysis. This is particularly useful for debugging agent interactions.
+
+`ObjectLogger` simply serializes objects to a pickle file. It first removes unserializeable parts of the objects (e.g. like `async` managers).
+
+#### Basic Usage
+
+```python
+from aixtools.utils.log_objects import ObjectLogger
+
+# Create a logger as a context manager
+with ObjectLogger() as logger:
+    # Log any pickleable object
+    logger.log({"message": "Hello, world!"})
+    
+    # Log agent responses or any other objects
+    logger.log(agent_response)
+```
+
+#### Logging Agent Interactions
+
+The function `run_agent` logs each node from the agent run, roughtly it looks like this:
+
+```python
+async def run_agent(agent: Agent, prompt: str | list[str]):
+    nodes = []
+    async with agent.iter(prompt) as agent_run:
+        with ObjectLogger(debug=debug) as agent_logger:
+            async for node in agent_run:
+                agent_logger.log(node)
+                nodes.append(node)
+            result = agent_run.result
+    return result.data, nodes
+```
+
+#### Saving Multiple Objects
+
+```python
+from aixtools.utils.log_objects import save_objects_to_logfile
+
+# Save a list of objects to a log file
+objects = [obj1, obj2, obj3]
+save_objects_to_logfile(objects)
+```
+
+### log_view App
+
+The `log_view` app allows you to visualize and analyze the objects logged by `ObjectLogger`.
+
+It is a simple Streamlit app that you can run locally and view the log files.
+
+#### Running the App
+
+You can run the app using the command-line script installed with the package:
+
+```bash
+log_view
+```
+
+Or specify a custom log directory:
+
+```bash
+log_view /path/to/logs
+```
+
+#### Features
+
+The log_view app provides several features for analyzing logged objects:
+
+- **Log File Selection**: Choose from available log files
+- **Filtering**: Filter nodes by text, type, attributes, or regex patterns
+- **Visualization**: Expand/collapse nodes to view details
+- **Export**: Export filtered nodes to JSON
+
+#### Example Workflow
+
+1. Log agent interactions using `ObjectLogger`
+2. Run the `log_view` app to analyze the logs
+3. Filter and explore the logged objects
+4. Export interesting findings for further analysis
+
+## Additional Utilities
+
+AIXtools provides several other utilities to support agent development:
+
+### PersistedDict
+
+A dictionary that persists to a file on disk as JSON or pickle:
+
+```python
+from aixtools.utils.persisted_dict import PersistedDict
+
+# Create a persisted dictionary
+data = PersistedDict("data.json")
+
+# Use it like a regular dictionary
+data["key"] = "value"  # Automatically saved to disk
+```
+
+## Agent Utilities
+
+Functions for creating and running agents with different model providers:
+
+```python
+from aixtools.agents.agent import get_agent, run_agent
+
+# Create an agent with the default model (from MODEL_FAMILY)
+agent = get_agent(system_prompt="You are a helpful assistant.")
+
+# Create an agent with a specific model
+from aixtools.agents.agent import get_model_openai
+model = get_model_openai()
+agent = get_agent(system_prompt="You are a helpful assistant.", model=model)
+
+# Run the agent
+result, nodes = await run_agent(agent, "Tell me about AI")
+```
+
+### Batch Processing
+
+Run multiple agent queries simultaneously:
+
+```python
+from aixtools.agents.agent_batch import agent_batch, AgentQueryParams
+
+# Create query parameters
+query_parameters = [
+    AgentQueryParams(prompt="What is the meaning of life"),
+    AgentQueryParams(prompt="Who is the prime minister of Canada")
+]
+
+# Run queries in batches
+async for result in agent_batch(query_parameters):
+    print(result)
+```
+
+## Project Structure
+
+```
+aixtools/
+├── __init__.py           # Package initialization
+├── log_view.py           # Entry point for log_view app
+├── agents/               # Agent-related functionality
+│   ├── agent.py          # Core agent functions
+│   └── agent_batch.py    # Batch processing for agents
+├── log_view/             # Log viewer application
+│   ├── app.py            # Main Streamlit application
+│   ├── display.py        # Node display utilities
+│   ├── export.py         # Export functionality
+│   ├── filters.py        # Node filtering
+│   ├── log_utils.py      # Log file utilities
+│   └── node_utils.py     # Node processing utilities
+└── utils/                # Utility functions and classes
+    ├── config.py         # Configuration utilities
+    ├── log_objects.py    # Object logging functionality
+    ├── persisted_dict.py # Persistent dictionary
+    └── utils.py          # General utilities
+
+## Logging
+
+The logging system is configured using a standard Python `dictConfig` schema. By default, it will look for a `logging.yaml` or `logging.json` file in your project's root directory. You can also specify a custom path using the `LOGGING_CONFIG_PATH` environment variable.
+
+If no configuration file is found, a default colorized console logger will be used.
+
+### Example `logging.yaml`
+
+```yaml
+version: 1
+disable_existing_loggers: false
+formatters:
+  default:
+    format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+  color:
+    "()": "colorlog.ColoredFormatter"
+    "format": "%(log_color)s%(levelname)-8s%(reset)s [%(name)s] %(message)s"
+handlers:
+  console:
+    class: colorlog.StreamHandler
+    formatter: color
+    level: DEBUG
+  file:
+    class: logging.handlers.RotatingFileHandler
+    formatter: default
+    filename: app.log
+    maxBytes: 10485760 # 10MB
+    backupCount: 5
+    level: INFO
+root:
+  handlers: [console, file]
+  level: DEBUG
+loggers:
+  aixtools:
+    level: INFO
+```

aixtools-0.1.0/aixtools/__init__.py

@@ -0,0 +1,5 @@
+"""
+AiXtools - Tools for AI exploration and debugging
+"""
+
+__version__ = "0.1.0"

aixtools-0.1.0/aixtools/a2a/__init__.py

@@ -0,0 +1,5 @@
+"""A2A (Agent-to-Agent) communication utilities."""
+
+from .utils import fetch_agent_card, task, text_message, tool2skill
+
+__all__ = ["fetch_agent_card", "task", "text_message", "tool2skill"]