vantage-agents 0.1.0__tar.gz

vantage_agents-0.1.0/.env.example

@@ -0,0 +1,4 @@
+OPENAI_API_KEY=
+OPENAI_BASE_URL=https://api.openai.com/v1
+GROQ_API_KEY=
+GROQ_BASE_URL=https://api.groq.com/openai/v1

vantage_agents-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @saqlain2204

vantage_agents-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Report a reproducible defect
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To reproduce**
+Steps to reproduce the behaviour:
+1. ...
+2. ...
+
+**Expected behaviour**
+What you expected to happen.
+
+**Actual behaviour**
+What actually happened. Include the full traceback if applicable.
+
+**Environment**
+- Vantage version:
+- Python version:
+- OS:
+
+**Minimal reproducible example**
+```python
+# paste code here
+```

vantage_agents-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+labels: enhancement
+---
+
+**Summary**
+A short description of the feature you would like.
+
+**Motivation**
+Why is this feature useful? What problem does it solve?
+
+**Proposed solution**
+How would you implement this? (optional, but helpful)
+
+**Alternatives considered**
+Have you considered any alternative approaches?

vantage_agents-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Summary
+
+<!-- One sentence describing what this PR does -->
+
+## Changes
+
+<!-- Bullet list of what was changed and why -->
+
+## Checklist
+
+- [ ] Tests added or updated for every changed behaviour
+- [ ] All existing tests pass (`python -m pytest -q`)
+- [ ] Type annotations present on all new public symbols
+- [ ] `mypy src/vantage` passes
+- [ ] `ruff check .` passes
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`

vantage_agents-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12"]
+        os: [ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: python -m ruff check .
+
+      - name: Type-check with mypy
+        run: python -m mypy src/vantage
+
+      - name: Run tests
+        run: python -m pytest --cov=vantage --cov-report=xml -q
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

vantage_agents-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distribution
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

vantage_agents-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.DS_Store
+.env
+.idea/
+.vscode/
+dist/
+build/
+*.egg-info/
+

vantage_agents-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-03-30
+
+### Added
+- `Agent` for synchronous single-agent and multi-agent flows.
+- `AsyncAgent` with `run()` and `stream()` for async/streaming usage.
+- `OpenAIModel` and `GroqModel` sync LLM clients.
+- `AsyncOpenAIModel` and `AsyncGroqModel` async LLM clients with SSE streaming.
+- `LocalMemory` for in-process conversation history.
+- `Calculator` built-in tool using a safe AST-based evaluator.
+- `HandoverTool` for routing between agents in multi-agent flows.
+- `run_yaml_agent` and `async_run_yaml_agent` for YAML-driven agent execution.
+- `save_trace_png` for rendering execution traces as PNG diagrams.
+- New flat YAML format: `model: provider/model-name` — no `providers:` block required.
+- `response_schema` shorthand: `{field: type}` expanded to full JSON Schema automatically.
+- GitHub Actions CI pipeline (Python 3.11 / 3.12 / 3.13, ubuntu / windows / macos).
+- GitHub Actions publish workflow for PyPI releases.

vantage_agents-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to Vantage
+
+Thank you for your interest in contributing to Vantage.
+
+## Development setup
+
+```bash
+git clone https://github.com/saqlain2204/vantage.git
+cd vantage
+python -m venv .venv
+# Windows
+.venv\Scripts\activate
+# Linux / macOS
+source .venv/bin/activate
+
+pip install -e ".[dev]"
+cp .env.example .env   # fill in your API keys
+```
+
+## Workflow
+
+1. **Fork** the repository and clone your fork.
+2. **Create a branch** — one branch per feature or bug fix.
+3. **Make your changes** and add tests under `tests/`.
+4. **Fix any lint errors** automatically:
+   ```bash
+   make lint-fix
+   ```
+5. **Verify** the full check suite passes:
+   ```bash
+   make lint
+   make test
+   ```
+   Or manually:
+   ```bash
+   python -m ruff check .
+   python -m mypy src/vantage
+   python -m pytest -q
+   ```
+6. **Submit a Pull Request** against `main`.
+
+## Code conventions
+
+- Follow PEP 8 and PEP 526.
+- Use type annotations on all public functions and methods.  The project targets `mypy --strict` compliance.
+- Keep components modular and single-purpose.
+- Async counterparts (`AsyncAgent`, `AsyncOpenAIModel`, etc.) must mirror the sync API exactly.
+- Do not add dependencies to `pyproject.toml` without discussion in an issue first.
+
+## Tests
+
+All new features and bug fixes must include tests.  Run the suite with:
+
+```bash
+python -m pytest -q
+```
+
+For coverage:
+
+```bash
+python -m pytest --cov=vantage --cov-report=term-missing -q
+```
+
+Async tests use `pytest-asyncio`.  Mark them with `@pytest.mark.asyncio`.
+
+## Commit messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+feat: add Redis memory backend
+fix: correct tool_calls serialisation in OpenAI client
+docs: update Quick Start YAML example
+chore: bump Pillow to 11.0
+```
+
+## Changelog
+
+Update `CHANGELOG.md` under the `[Unreleased]` heading for every user-visible change.
+

vantage_agents-0.1.0/LICENSE

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

vantage_agents-0.1.0/Makefile

@@ -0,0 +1,45 @@
+.PHONY: help setup install test lint lint-fix typecheck format coverage
+
+# Override with: make setup PYTHON=python3.11
+PYTHON ?= python
+
+help:
+	@echo "Vantage — available targets:"
+	@echo ""
+	@echo "  setup      Create a virtual environment and install all dependencies"
+	@echo "  install    Install the package in editable mode"
+	@echo "  test       Run the test suite with pytest"
+	@echo "  lint       Run ruff and mypy"
+	@echo "  lint-fix   Auto-fix ruff lint errors"
+	@echo "  typecheck  Run mypy only"
+	@echo "  format     Auto-format source with ruff"
+	@echo "  coverage   Run tests and produce an HTML coverage report"
+
+setup:
+	$(PYTHON) -m venv .venv
+	$(PYTHON) -m pip install --upgrade pip
+	$(PYTHON) -m pip install -e ".[dev]"
+
+install:
+	$(PYTHON) -m pip install -e .
+
+test:
+	$(PYTHON) -m pytest -q
+
+lint:
+	$(PYTHON) -m ruff check .
+	$(PYTHON) -m mypy src/vantage
+
+lint-fix:
+	$(PYTHON) -m ruff check --fix .
+
+typecheck:
+	$(PYTHON) -m mypy src/vantage
+
+format:
+	$(PYTHON) -m ruff format .
+	$(PYTHON) -m ruff check . --fix
+
+coverage:
+	$(PYTHON) -m pytest --cov=vantage --cov-report=html --cov-report=term-missing -q
+

vantage_agents-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: vantage-agents
+Version: 0.1.0
+Summary: A modular and extensible Python library for building AI agents.
+Project-URL: Homepage, https://github.com/saqlain2204/vantage
+Project-URL: Issues, https://github.com/saqlain2204/vantage/issues
+Author-email: Saqlain <saqlain2204@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Vantage
+
+<p align="center">
+    <img src="assets/logo.png" alt="Vantage Logo" width="400" height="400" />
+</p>
+
+**A lightweight, protocol-first Python library for building AI agents.**
+
+[![CI](https://github.com/saqlain2204/vantage/actions/workflows/ci.yml/badge.svg)](https://github.com/saqlain2204/vantage/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/vantage-agents.svg)](https://badge.fury.io/py/vantage-agents)
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Vantage is a modular Python library for building AI agents. It follows SOLID principles and defines every component — LLMs, tools, and memory — as an abstract interface, making each one independently replaceable without changing agent logic.
+
+## Features
+
+- **Simple YAML configuration**: Define agents, models, and tools in a flat, human-readable YAML file. No boilerplate.
+- **Swappable components**: Implement `LLMBase`, `ToolBase`, or `MemoryBase` to replace any layer transparently.
+- **Multi-agent flows**: Route requests between specialised agents with `HandoverTool`.
+- **Sync and async**: Full async support with token streaming alongside the synchronous API.
+- **Execution tracing**: Export a PNG diagram of every step in an agent's execution via `save_trace_png`.
+- **Structured output**: Request JSON-schema-validated responses with a one-line field shorthand.
+
+## Installation
+
+```bash
+pip install vantage-agents
+```
+
+## Quick Start
+
+### Python API
+
+```python
+from vantage.core import Agent
+from vantage.llms import OpenAIModel
+from vantage.memory import LocalMemory
+from vantage.tools import Calculator
+
+agent = Agent(
+    llm=OpenAIModel(model="gpt-4o-mini"),
+    tools=[Calculator()],
+    memory=LocalMemory(),
+    system_prompt="You are a math assistant.",
+)
+
+response = agent.run("What is (12 + 8) / 5?")
+print(response.content)
+```
+
+### YAML configuration
+
+Define agents in a YAML file — the `model` key sets both the provider and the model in one line:
+
+```yaml
+agents:
+  calc_bot:
+    model: groq/llama-3.3-70b-versatile
+    system_prompt: "You are a math assistant. Use the calculator tool for arithmetic."
+    tools: [calculator]
+    response_schema:
+      result: number
+      explanation: string
+```
+
+```python
+from vantage import run_yaml_agent
+from vantage.tools import Calculator
+
+resp = run_yaml_agent("agents.yaml", "calc_bot", "What is 15 * 12?", tools=[Calculator()])
+print(resp.content)
+```
+
+`response_schema` accepts a flat `{field: type}` shorthand that is automatically expanded to a full JSON Schema. Supported types: `string`, `number`, `integer`, `boolean`, `array`, `object`.
+
+### Async and streaming
+
+```python
+import asyncio
+from vantage.core import AsyncAgent
+from vantage.llms import AsyncOpenAIModel
+
+agent = AsyncAgent(
+    llm=AsyncOpenAIModel(model="gpt-4o-mini"),
+    system_prompt="You are helpful.",
+)
+
+async def main() -> None:
+    async for token in agent.stream("Explain gradient descent briefly."):
+        print(token, end="", flush=True)
+
+asyncio.run(main())
+```
+
+## Architecture
+
+```mermaid
+graph TD
+    A[Agent / AsyncAgent] --> B[LLMBase]
+    A --> C[MemoryBase]
+    A --> D[ToolBase]
+    B --> B1[OpenAIModel / AsyncOpenAIModel]
+    B --> B2[GroqModel / AsyncGroqModel]
+    C --> C1[LocalMemory]
+    D --> D1[Calculator]
+    D --> D2[HandoverTool]
+    D --> D3[Custom Tools]
+```
+
+Every arrow in the diagram is an interface boundary — swap any node without touching the others.
+
+## Extending Vantage
+
+### Custom tool
+
+```python
+from vantage.core import ToolBase
+
+class WeatherTool(ToolBase):
+    @property
+    def name(self) -> str:
+        return "get_weather"
+
+    @property
+    def description(self) -> str:
+        return "Return the current weather for a city."
+
+    def input_schema(self):
+        return {
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+            "additionalProperties": False,
+        }
+
+    def execute(self, **kwargs) -> str:
+        city = kwargs["city"]
+        return f"Sunny, 22 C in {city}"   # replace with a real API call
+```
+
+### Custom LLM backend
+
+```python
+from vantage.core import LLMBase
+from vantage.core.models import Message, Role
+
+class MyLLM(LLMBase):
+    def generate(self, messages, tools, response_schema=None) -> Message:
+        # call your backend here
+        return Message(role=Role.ASSISTANT, content="...")
+```
+
+## Multi-agent flows
+
+```python
+from vantage import run_yaml_agent, Calculator
+from vantage.core.handovers import HandoverTool
+
+tools = [
+    Calculator(),
+    HandoverTool("math_expert", "Transfer to the math expert."),
+    HandoverTool("word_expert", "Transfer to the word expert."),
+]
+
+resp = run_yaml_agent("agents.yaml", "gatekeeper", "What is 6 * 7?", tools=tools)
+print(resp.content)
+```
+
+## Execution tracing
+
+Every `AgentResponse` carries a `trace` list. Render it as a PNG:
+
+```python
+from vantage import save_trace_png
+
+save_trace_png(resp.trace, "trace.png")
+```
+
+The diagram shows every step — user input, LLM reasoning, tool calls, tool results, and the final answer — with the actual content of each step.
+
+## Running the examples
+
+```bash
+git clone https://github.com/saqlain2204/vantage.git
+cd vantage
+pip install -e ".[dev]"
+cp .env.example .env          # add your API keys
+
+python -m examples.calculator_agent.run
+python -m examples.custom_tool_agent.run
+python -m examples.multi_agent_flow.run
+```
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, coding conventions, and how to submit a pull request.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the version history.
+
+## License
+
+Vantage is released under the [MIT License](LICENSE).
+