explainable-agent 0.1.0__tar.gz

explainable_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emre
+
+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.

explainable_agent-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: explainable-agent
+Version: 0.1.0
+Summary: A local-first, explainable AI agent framework with self-healing, detailed error diagnostics, and interactive tool-calling traces.
+Author: Emre
+License: MIT
+Project-URL: Repository, https://github.com/emredeveloper/explainable-agent-lab
+Project-URL: Issues, https://github.com/emredeveloper/explainable-agent-lab/issues
+Keywords: agent,llm,tool-calling,evaluation,xai,self-healing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.54.0
+Requires-Dist: json-repair>=0.30.3
+Requires-Dist: tenacity>=8.2.3
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: ddgs>=0.1.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Requires-Dist: build>=1.2.1; extra == "dev"
+Dynamic: license-file
+
+# 🔬 Explainable Agent Lab
+
+> A local-first, explainable agent framework designed to guide developers in building robust AI agents.
+
+Building reliable agents is hard. LLMs hallucinate, get stuck in infinite loops, or fail to parse tools correctly. **Explainable Agent Lab** is built to solve this by focusing on **explainability and guidance**.
+
+✨ **Key Features:**
+- **Show the Hidden Errors:** Reveal exactly where and why an agent fails (e.g., low confidence, schema violations).
+- **Self-Healing:** The agent automatically analyzes its own errors and proposes alternative tool-based solutions.
+- **Visual Terminal Tracking:** Step-by-step interactive and colorful tracking using the `rich` library (`--verbose`).
+- **Detailed Diagnostic Reports:** Actionable suggestions on hallucination risks, loop patterns, and prompt improvements.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install
+```bash
+# Recommended: Editable install
+python -m venv .venv
+# On Windows:
+.venv\Scripts\activate
+# On Mac/Linux:
+# source .venv/bin/activate
+
+pip install -e .[dev]
+```
+
+### 2. Connect Your Local LLM
+You can use any OpenAI-compatible local server like **Ollama** or **LM Studio**.
+
+- **Ollama:** `http://localhost:11434/v1` (e.g., model: `ministral-3:14b`)
+- **LM Studio:** `http://localhost:1234/v1` (e.g., model: `gpt-oss-20b`)
+
+*Tip: Copy `.env.example` to `.env` to set your defaults.*
+
+### 3. Run the Agent
+**Example using Ollama:**
+```bash
+python -m explainable_agent.cli \
+  --base-url http://localhost:11434/v1 \
+  --model ministral-3:14b \
+  --task "calculate_math: (215*4)-12" \
+  --verbose
+```
+
+---
+
+## 💻 Using the Python API
+
+Easily integrate the agent into your codebase or create custom tools using the `@define_tool` decorator. 
+
+Check out the `examples/` directory:
+- [`examples/basic_usage.py`](examples/basic_usage.py) - Initialize and run the agent programmatically.
+- [`examples/custom_tool_usage.py`](examples/custom_tool_usage.py) - Learn how to build custom tools and watch the agent self-heal from errors.
+
+Run an example:
+```bash
+python examples/custom_tool_usage.py
+```
+
+---
+
+## 📊 Evaluation & Custom Datasets
+
+Evaluate your fine-tuned models or custom datasets easily. The pipeline parses messy outputs, repairs broken JSON, and generates actionable Markdown reports.
+
+**1. Create a `.jsonl` dataset** (See `examples/custom_eval_sample.jsonl`)
+
+**2. Run the evaluation:**
+```bash
+python scripts/eval_hf_tool_calls.py \
+  --dataset examples/custom_eval_sample.jsonl \
+  --model ministral-3:14b
+```
+
+We also support standard benchmarks out of the box:
+- **HF Tool Calls:** `data/evals/hf_xlam_fc_sample.jsonl`
+- **BFCL SQL:** `data/evals/bfcl_sql/BFCL_v3_sql.json`
+- **SWE-bench Lite:** `data/evals/swebench_lite_test.jsonl`
+
+---
+
+## 🛠️ Built-in Tools
+The agent comes with out-of-the-box tools ready to use:
+`duckduckgo_search`, `calculate_math`, `read_text_file`, `list_workspace_files`, `now_utc`, `sqlite_init_demo`, `sqlite_list_tables`, `sqlite_describe_table`, `sqlite_query`, `sqlite_execute`.
+
+---
+*License: MIT | Current Release: v0.1.0*

explainable_agent-0.1.0/README.md

@@ -0,0 +1,89 @@
+# 🔬 Explainable Agent Lab
+
+> A local-first, explainable agent framework designed to guide developers in building robust AI agents.
+
+Building reliable agents is hard. LLMs hallucinate, get stuck in infinite loops, or fail to parse tools correctly. **Explainable Agent Lab** is built to solve this by focusing on **explainability and guidance**.
+
+✨ **Key Features:**
+- **Show the Hidden Errors:** Reveal exactly where and why an agent fails (e.g., low confidence, schema violations).
+- **Self-Healing:** The agent automatically analyzes its own errors and proposes alternative tool-based solutions.
+- **Visual Terminal Tracking:** Step-by-step interactive and colorful tracking using the `rich` library (`--verbose`).
+- **Detailed Diagnostic Reports:** Actionable suggestions on hallucination risks, loop patterns, and prompt improvements.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install
+```bash
+# Recommended: Editable install
+python -m venv .venv
+# On Windows:
+.venv\Scripts\activate
+# On Mac/Linux:
+# source .venv/bin/activate
+
+pip install -e .[dev]
+```
+
+### 2. Connect Your Local LLM
+You can use any OpenAI-compatible local server like **Ollama** or **LM Studio**.
+
+- **Ollama:** `http://localhost:11434/v1` (e.g., model: `ministral-3:14b`)
+- **LM Studio:** `http://localhost:1234/v1` (e.g., model: `gpt-oss-20b`)
+
+*Tip: Copy `.env.example` to `.env` to set your defaults.*
+
+### 3. Run the Agent
+**Example using Ollama:**
+```bash
+python -m explainable_agent.cli \
+  --base-url http://localhost:11434/v1 \
+  --model ministral-3:14b \
+  --task "calculate_math: (215*4)-12" \
+  --verbose
+```
+
+---
+
+## 💻 Using the Python API
+
+Easily integrate the agent into your codebase or create custom tools using the `@define_tool` decorator. 
+
+Check out the `examples/` directory:
+- [`examples/basic_usage.py`](examples/basic_usage.py) - Initialize and run the agent programmatically.
+- [`examples/custom_tool_usage.py`](examples/custom_tool_usage.py) - Learn how to build custom tools and watch the agent self-heal from errors.
+
+Run an example:
+```bash
+python examples/custom_tool_usage.py
+```
+
+---
+
+## 📊 Evaluation & Custom Datasets
+
+Evaluate your fine-tuned models or custom datasets easily. The pipeline parses messy outputs, repairs broken JSON, and generates actionable Markdown reports.
+
+**1. Create a `.jsonl` dataset** (See `examples/custom_eval_sample.jsonl`)
+
+**2. Run the evaluation:**
+```bash
+python scripts/eval_hf_tool_calls.py \
+  --dataset examples/custom_eval_sample.jsonl \
+  --model ministral-3:14b
+```
+
+We also support standard benchmarks out of the box:
+- **HF Tool Calls:** `data/evals/hf_xlam_fc_sample.jsonl`
+- **BFCL SQL:** `data/evals/bfcl_sql/BFCL_v3_sql.json`
+- **SWE-bench Lite:** `data/evals/swebench_lite_test.jsonl`
+
+---
+
+## 🛠️ Built-in Tools
+The agent comes with out-of-the-box tools ready to use:
+`duckduckgo_search`, `calculate_math`, `read_text_file`, `list_workspace_files`, `now_utc`, `sqlite_init_demo`, `sqlite_list_tables`, `sqlite_describe_table`, `sqlite_query`, `sqlite_execute`.
+
+---
+*License: MIT | Current Release: v0.1.0*

explainable_agent-0.1.0/explainable_agent/__init__.py

@@ -0,0 +1,8 @@
+"""Explainable local agent MVP."""
+
+from .agent import ExplainableAgent
+from .config import Settings
+
+__version__ = "0.1.0"
+
+__all__ = ["ExplainableAgent", "Settings", "__version__"]