roy-ollama-toolkit 0.2.2__tar.gz

roy_ollama_toolkit-0.2.2/PKG-INFO

@@ -0,0 +1,454 @@
+Metadata-Version: 2.4
+Name: roy-ollama-toolkit
+Version: 0.2.2
+Summary: A Professional-Grade, Modular Agentic Framework for Ollama & LiteLLM.
+Project-URL: Homepage, https://github.com/imyourboyroy/ollamatoolkit
+Project-URL: Repository, https://github.com/imyourboyroy/ollamatoolkit
+Project-URL: Issues, https://github.com/imyourboyroy/ollamatoolkit/issues
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ollama>=0.6.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: litellm>=1.50.0
+Requires-Dist: llm-telemetry-toolkit>=0.1.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.2.0
+Requires-Dist: web-scraper-toolkit>=0.1.7
+Requires-Dist: pymupdf>=1.26.7
+Requires-Dist: pypdf>=6.5.0
+Requires-Dist: emailtoolkit>=0.1.0
+Provides-Extra: system
+Requires-Dist: psutil>=7.1.3; extra == "system"
+Provides-Extra: files
+Requires-Dist: pypdf>=6.4.1; extra == "files"
+Requires-Dist: pdf2image>=1.16.0; extra == "files"
+Requires-Dist: opencv-python-headless>=4.0.0; extra == "files"
+Provides-Extra: email
+Requires-Dist: emailtoolkit[dns]>=0.1.0; extra == "email"
+Provides-Extra: full
+Requires-Dist: psutil>=7.1.3; extra == "full"
+Requires-Dist: pypdf>=6.4.1; extra == "full"
+Requires-Dist: pdf2image>=1.16.0; extra == "full"
+Requires-Dist: opencv-python-headless>=4.0.0; extra == "full"
+Requires-Dist: emailtoolkit[dns]>=0.1.0; extra == "full"
+
+# OllamaToolkit
+
+## Use Case Synopsis
+`ollamatoolkit` is a modular, pip-installable toolkit for building reliable local-AI and hybrid-AI systems on top of Ollama. It is designed for:
+- **agentic workflows** (single agent + multi-agent teams),
+- **programmatic automation** (sync/async clients, typed responses, streaming events),
+- **tool orchestration** (web, files, vector/RAG, DB, system, email, schema, vision), and
+- **integration into larger systems** (research pipelines, MCP-connected tools, telemetry-enabled apps).
+
+If your goal is “make smaller local models perform consistently through good scaffolding,” this package is built for exactly that.
+
+---
+
+## Installation
+
+```bash
+# Core
+pip install roy-ollama-toolkit
+
+# Full extras (system + file/image + email tooling)
+pip install "roy-ollama-toolkit[full]"
+```
+
+Supported Python versions: **3.10–3.13**.
+Import path remains `ollamatoolkit` after installation.
+
+---
+
+## Integration Guide
+
+### 1) Standalone usage (direct Python)
+
+```python
+from ollamatoolkit.client import OllamaClient
+
+with OllamaClient(base_url="http://localhost:11434") as client:
+    reply = client.chat(
+        model="qwen3:8b",
+        messages=[{"role": "user", "content": "Give me a 1-line business summary."}],
+    )
+    print(reply.message.content)
+```
+
+### 2) Agentic usage (SimpleAgent + tools)
+
+```python
+from ollamatoolkit.agents.simple import SimpleAgent
+
+agent = SimpleAgent(
+    name="research-assistant",
+    system_message="You are concise, evidence-focused, and tool-using.",
+    model_config={"model": "ollama/qwen3:8b", "base_url": "http://localhost:11434"},
+)
+
+@agent.tool()
+def add(a: int, b: int) -> int:
+    """Add two integers."""
+    return a + b
+
+print(agent.run("What is 19 + 23?"))
+```
+
+### 3) Agentic + MCP tool servers (stdio bridge)
+
+`ollamatoolkit.tools.mcp` connects to MCP servers via **command + args** (stdio JSON-RPC).
+
+```python
+from ollamatoolkit.tools.mcp import MCPToolManager
+from ollamatoolkit.agents.simple import SimpleAgent
+
+mcp = MCPToolManager(
+    {
+        "web": {
+            "command": "python",
+            "args": ["-m", "web_scraper_toolkit.server.mcp_server"],
+        }
+    }
+)
+mcp.start_all()
+
+agent = SimpleAgent(
+    name="mcp-agent",
+    system_message="Use tools when helpful.",
+    model_config={"model": "ollama/qwen3:8b", "base_url": "http://localhost:11434"},
+    tools=mcp.get_tool_schemas(),
+    function_map=mcp.get_proxy_functions(),
+)
+
+print(agent.run("Find contact info for example.com and summarize it."))
+mcp.shutdown()
+```
+
+> For remote MCP hosting, run the server on the remote machine and use a transport command that exposes stdio locally (for example via SSH command invocation).
+
+---
+
+## Quick API Starts
+
+### Sync + Async parity
+
+```python
+import asyncio
+from ollamatoolkit.client import OllamaClient, AsyncOllamaClient
+
+with OllamaClient() as client:
+    print(client.version())
+
+async def main() -> None:
+    async with AsyncOllamaClient() as client:
+        print(await client.version())
+
+asyncio.run(main())
+```
+
+### Stream structured events
+
+```python
+from ollamatoolkit.client import OllamaClient
+
+with OllamaClient() as client:
+    for event in client.stream_chat_events(
+        model="qwen3:8b",
+        messages=[{"role": "user", "content": "Explain caching in 2 bullets."}],
+    ):
+        if event.event == "token":
+            print(event.text, end="", flush=True)
+```
+
+### OpenAI-compatible `/v1/*` helpers
+
+```python
+from ollamatoolkit.client import OllamaClient
+
+with OllamaClient() as client:
+    models = client.openai_list_models()
+    chat = client.openai_chat_completions(
+        model="qwen3:8b",
+        messages=[{"role": "user", "content": "One sentence about B2B lead qualification."}],
+    )
+    print(chat.choices[0].message.content)
+```
+
+### Structured extraction
+
+```python
+from pydantic import BaseModel
+from ollamatoolkit.agents.simple import SimpleAgent
+
+class CompanyFacts(BaseModel):
+    website: str
+    ceo_name: str
+
+agent = SimpleAgent(
+    name="extractor",
+    system_message="Return valid JSON only.",
+    model_config={"model": "ollama/qwen3:8b", "base_url": "http://localhost:11434"},
+)
+
+facts = agent.run_structured("Extract website and CEO from: ...", CompanyFacts)
+print(facts.model_dump())
+```
+
+---
+
+## CLI Usage
+
+Entry point:
+
+```bash
+ollamatoolkit --help
+# or
+python -m ollamatoolkit.cli --help
+```
+
+### Commands
+
+#### `config`
+- `--init` create sample config JSON.
+
+#### `run`
+- positional: `role_file`
+- `--task/-t`
+- `--interactive/-i`
+- `--dashboard/-d`
+- `--model/-m`
+- `--tools` (`all files math db server system web vision`)
+- `--db-path`
+- `--config/-c`
+- `--batch-file/-b`
+- `--output-dir/-o`
+- `--streaming/-s`
+
+#### `models`
+- `--capability/-c` (`vision embedding tools completion reasoning`)
+- `--json`
+- `--base-url`
+
+#### `chat`
+- `--model/-m`
+- `--base-url`
+- `--system/-s`
+
+### Example commands
+
+```bash
+# Generate sample config
+python -m ollamatoolkit.cli config --init
+
+# Quick chat
+python -m ollamatoolkit.cli chat --model qwen3:8b
+
+# Run role-based agent with streaming
+python -m ollamatoolkit.cli run .\roles\researcher.json -t "Research Acme Corp" --streaming
+
+# List only embedding-capable models as JSON
+python -m ollamatoolkit.cli models --capability embedding --json
+```
+
+---
+
+## Configuration Hierarchy
+
+When running through CLI/runtime patterns, prefer this precedence:
+1. **Explicit runtime arguments** (CLI flags / constructor args)
+2. **Config file values** (`config.json` or generated sample config)
+3. **Dataclass defaults** in `ToolkitConfig`
+
+Primary config sections:
+- `agent`
+- `tools` (including `mcp_servers`)
+- `web`
+- `vision`
+- `vector`
+- `models` (per-capability slot config)
+- `memory`
+- `document`
+- `benchmark`
+- `telemetry`
+- `logging`
+- `dashboard`
+
+Load and save:
+
+```python
+from ollamatoolkit.config import ToolkitConfig
+
+cfg = ToolkitConfig.load("config.json")
+cfg.save("config.generated.json")
+```
+
+---
+
+## Architecture (high level)
+
+- **Client layer**: `ollamatoolkit.client` + `client_api/*`
+  - sync + async clients
+  - transport + retries/backoff/circuit breaker
+  - chat/generate/embed/model-management/web
+  - OpenAI-compat wrappers
+- **Agent layer**: `agents/simple.py`, `agents/team.py`, `agents/role.py`, `agents/memory.py`
+  - tool calling
+  - streaming token loops
+  - structured Pydantic responses
+  - multi-agent orchestration
+- **Tool layer**: `tools/*`
+  - vector, document, web, files, DB, math, email, schema, system, server
+  - vision subpackage for OCR/analysis/video/spatial tasks
+  - MCP client for external tool servers
+- **Model intelligence**: `models/selector.py`
+  - choose best model by capability
+
+---
+
+## Source File Map (what each file does)
+
+| File | Responsibility |
+|---|---|
+| `ollamatoolkit/__init__.py` | Ollama Toolkit - A Professional-Grade Agentic Framework |
+| `ollamatoolkit/agent.py` | Ollama Toolkit - Agent Shim |
+| `ollamatoolkit/agents/__init__.py` | Ollama Toolkit - Agent Components |
+| `ollamatoolkit/agents/memory.py` | Ollama Toolkit - Agent Memory Management |
+| `ollamatoolkit/agents/role.py` | Ollama Toolkit - Role Agent |
+| `ollamatoolkit/agents/simple.py` | Simple agent runtime for synchronous/async LiteLLM conversations with tool execution. |
+| `ollamatoolkit/agents/team.py` | Ollama Toolkit - Multi-Agent Team Orchestration |
+| `ollamatoolkit/callbacks.py` | OllamaToolkit Callbacks |
+| `ollamatoolkit/cli.py` | Ollama Toolkit - CLI Runner |
+| `ollamatoolkit/client.py` | Public client module for OllamaToolkit. |
+| `ollamatoolkit/client_api/__init__.py` | Composable client-domain adapters used by OllamaToolkit public client façades. |
+| `ollamatoolkit/client_api/async_client.py` | Public asynchronous Ollama client composed from endpoint-domain adapters. |
+| `ollamatoolkit/client_api/common.py` | Shared helpers for OllamaToolkit API clients. |
+| `ollamatoolkit/client_api/inference.py` | Inference endpoint adapters for OllamaToolkit clients. |
+| `ollamatoolkit/client_api/models.py` | Model-management endpoint adapters for OllamaToolkit clients. |
+| `ollamatoolkit/client_api/openai_compat.py` | OpenAI-compatible (`/v1/*`) endpoint adapters for OllamaToolkit clients. |
+| `ollamatoolkit/client_api/sync_client.py` | Public synchronous Ollama client composed from endpoint-domain adapters. |
+| `ollamatoolkit/client_api/transport.py` | HTTP transport layer used by OllamaToolkit client domain modules. |
+| `ollamatoolkit/client_api/web.py` | Web endpoint adapters for OllamaToolkit clients. |
+| `ollamatoolkit/common/utils.py` | Ollama Toolkit - Utilities |
+| `ollamatoolkit/config/__init__.py` | Ollama Toolkit - Configuration Package |
+| `ollamatoolkit/config/core.py` | Ollama Toolkit - Core Configuration |
+| `ollamatoolkit/config/presets.py` | Ollama Toolkit - Model Presets |
+| `ollamatoolkit/config.py` | Ollama Toolkit - Configuration |
+| `ollamatoolkit/connector.py` | High-level Ollama connector façade used by toolkit consumers and dependent apps. |
+| `ollamatoolkit/dashboard.py` | Ollama Toolkit - Mission Control Dashboard |
+| `ollamatoolkit/exceptions.py` | OllamaToolkit Exception Hierarchy |
+| `ollamatoolkit/extractor.py` | Schema-first field extraction helper built on top of ``SimpleAgent``. |
+| `ollamatoolkit/models/__init__.py` | Ollama Toolkit - Model Utilities |
+| `ollamatoolkit/models/selector.py` | Ollama Toolkit - Smart Model Selector |
+| `ollamatoolkit/openai_types.py` | Typed models for Ollama OpenAI-compatible (`/v1/*`) endpoints. |
+| `ollamatoolkit/telemetry.py` | Ollama Toolkit - Telemetry Integration |
+| `ollamatoolkit/tool_registry.py` | OllamaToolkit - LLM Tool Registry |
+| `ollamatoolkit/tools/__init__.py` | Ollama Toolkit - Tools Package |
+| `ollamatoolkit/tools/benchmark.py` | Ollama Toolkit - Model Benchmarking (GPU-Aware) |
+| `ollamatoolkit/tools/cache.py` | OllamaToolkit - Cache Tools |
+| `ollamatoolkit/tools/db.py` | Ollama Toolkit - Database Tools |
+| `ollamatoolkit/tools/document.py` | Ollama Toolkit - Document Processor |
+| `ollamatoolkit/tools/email.py` | OllamaToolkit - Email Tools |
+| `ollamatoolkit/tools/files.py` | Ollama Toolkit - File Tools |
+| `ollamatoolkit/tools/math.py` | Ollama Toolkit - Math Tools |
+| `ollamatoolkit/tools/mcp.py` | Ollama Toolkit - MCP Client |
+| `ollamatoolkit/tools/models.py` | Ollama Toolkit - Model Inspector |
+| `ollamatoolkit/tools/pdf.py` | PDF helper utilities shared by vision/document workflows. |
+| `ollamatoolkit/tools/schema.py` | OllamaToolkit - JSON Schema Tools |
+| `ollamatoolkit/tools/server.py` | Ollama Toolkit - Server Tools |
+| `ollamatoolkit/tools/system.py` | Ollama Toolkit - System Tools |
+| `ollamatoolkit/tools/system_health.py` | Ollama Toolkit - System Health Tool |
+| `ollamatoolkit/tools/vector.py` | Ollama Toolkit - Vector Intelligence (RAG) |
+| `ollamatoolkit/tools/vision/__init__.py` | Ollama Toolkit - Vision Package |
+| `ollamatoolkit/tools/vision/analysis.py` | Ollama Toolkit - Vision Analysis |
+| `ollamatoolkit/tools/vision/metadata.py` | Ollama Toolkit - Vision Metadata |
+| `ollamatoolkit/tools/vision/ocr.py` | OCR helper that routes image/PDF inputs through a vision-capable model. |
+| `ollamatoolkit/tools/vision/spatial.py` | Ollama Toolkit - Vision Spatial |
+| `ollamatoolkit/tools/vision/tiling.py` | Ollama Toolkit - Vision Tiling |
+| `ollamatoolkit/tools/vision/video.py` | Ollama Toolkit - Smart Video Processor |
+| `ollamatoolkit/tools/web.py` | Ollama Toolkit - Web Tools |
+| `ollamatoolkit/types.py` | Ollama Toolkit - Type Definitions |
+| `ollamatoolkit/utils.py` | Ollama Toolkit - Utilities |
+
+---
+
+## Examples Directory
+
+The `examples/` folder includes runnable patterns:
+- `01_basic_chat.py`
+- `02_with_tools.py`
+- `03_vision_ocr.py`
+- `04_rag_pipeline.py`
+- `05_multi_agent_team.py`
+- `06_streaming_ui.py`
+- `07_schema_cache.py`
+- `08_email_tools.py`
+- `09_tool_registry.py`
+
+---
+
+## Testing and Quality
+
+```bash
+# Lint
+python -m ruff check .
+
+# Format
+python -m ruff format .
+
+# Type-check
+python -m mypy src/ollamatoolkit
+
+# Tests
+python -B -m pytest -q
+```
+
+Optional live Ollama integration tests (env-gated):
+
+```bash
+# PowerShell example (do not hardcode private hosts in tracked files)
+$env:OLLAMA_TEST_BASE_URL="http://YOUR_HOST:11434"
+python -m pytest tests/test_live_ollama_integration.py -m integration -v
+```
+
+Workspace gateway (run from workspace root):
+
+```bash
+python .\tools\run_quality_gate.py --project .\OllamaToolkit
+```
+
+---
+
+## Publishing Checklist (GitHub + PyPI)
+
+From workspace root:
+
+```bash
+python .\tools\run_quality_gate.py --project .\OllamaToolkit
+python .\tools\publish_release.py --project .\OllamaToolkit
+```
+
+---
+
+## Security & Privacy Notes
+
+- Do not commit private server IPs, API keys, or machine-specific paths.
+- Use environment variables for private runtime endpoints.
+- Keep local-only testing settings in ignored files (e.g., local config files excluded by `.gitignore`).
+
+---
+
+## Author
+
+**Created by**: Roy Dawson IV  
+**GitHub**: [https://github.com/imyourboyroy](https://github.com/imyourboyroy)  
+**PyPI**: [https://pypi.org/user/ImYourBoyRoy/](https://pypi.org/user/ImYourBoyRoy/)