pico-agent 0.1.0__tar.gz

pico_agent-0.1.0/.coveragerc

@@ -0,0 +1,17 @@
+[run]
+branch = True
+source =
+    pico_agent
+omit =
+    */_version.py
+
+[paths]
+pico_agent =
+    src/pico_agent
+    .tox/*/lib/*/site-packages/pico_agent
+    .tox/*/site-packages/pico_agent
+    */site-packages/pico_agent
+
+[report]
+show_missing = True
+

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

@@ -0,0 +1,102 @@
+name: CI & Coverage
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  tests:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install tox
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+
+      - name: Run tests with coverage (writes to repo root)
+        shell: bash
+        run: |
+          set -euxo pipefail
+          tox -e cov
+          # Rename to per-version file for artifact + merge job
+          mv .coverage .coverage.${{ matrix.python-version }}
+          ls -la .coverage.${{ matrix.python-version }}
+
+      - name: Upload .coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
+          if-no-files-found: error
+
+  coverage-merge:
+    name: Merge coverage
+    runs-on: ubuntu-latest
+    needs: tests
+    steps:
+      - name: Checkout (for repo context)
+        uses: actions/checkout@v4
+
+      - name: Download all coverage artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: coverage-reports
+
+      - name: Combine coverage and generate reports
+        shell: bash
+        run: |
+          set -euxo pipefail
+          python -m pip install coverage
+          files=$(find coverage-reports -type f -name ".coverage.*" -print)
+          if [ -z "$files" ]; then
+            echo "No coverage data files found"; exit 1
+          fi
+          coverage combine $files
+          coverage report -m --rcfile=.coveragerc
+          coverage xml -o coverage.xml --rcfile=.coveragerc
+          coverage html -d htmlcov --rcfile=.coveragerc
+
+      - name: Upload combined coverage XML
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: error
+
+      - name: Upload HTML coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: htmlcov
+          if-no-files-found: error
+
+      - name: Upload to Codecov
+        if: always() && !cancelled()
+        uses: codecov/codecov-action@v5
+        continue-on-error: true
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: dperezcabrera/pico-agent
+

pico_agent-0.1.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,36 @@
+name: Publish Python Package to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
+    - name: Install build deps
+      run: python -m pip install --upgrade pip build
+
+    - name: Build package
+      run: python -m build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        skip-existing: true
+        verify-metadata: true
+        attestations: false
+

pico_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Pérez Cabrera
+
+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.

pico_agent-0.1.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+include LICENSE
+
+recursive-include src *.py
+
+recursive-include tests *.py
+
+exclude .gitignore
+exclude Dockerfile*
+exclude docker-compose*.yml
+exclude Makefile
+
+prune build
+prune dist
+prune .tox
+prune .pytest_cache
+prune __pycache__
+

pico_agent-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: pico-agent
+Version: 0.1.0
+Summary: A pico agent framework with LangChain integration.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 David Pérez Cabrera
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-agent
+Project-URL: Repository, https://github.com/dperezcabrera/pico-agent
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-agent/issues
+Keywords: ioc,di,dependency injection,agent,llm,langchain,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pico-ioc>=2.2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: langchain>=1.0.2
+Requires-Dist: langchain-core
+Requires-Dist: langchain-community
+Requires-Dist: langchain-model-profiles
+Provides-Extra: openai
+Requires-Dist: langchain-openai; extra == "openai"
+Provides-Extra: google
+Requires-Dist: langchain-google-genai; extra == "google"
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic; extra == "anthropic"
+Provides-Extra: community
+Requires-Dist: langchain-community; extra == "community"
+Provides-Extra: all
+Requires-Dist: langchain-openai; extra == "all"
+Requires-Dist: langchain-google-genai; extra == "all"
+Requires-Dist: langchain-anthropic; extra == "all"
+Requires-Dist: langchain-community; extra == "all"
+Dynamic: license-file

pico_agent-0.1.0/README.md

@@ -0,0 +1,228 @@
+# 📦 pico-agent
+
+[![PyPI](https://img.shields.io/pypi/v/pico-agent.svg)](https://pypi.org/project/pico-agent/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-ioc/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-agent/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-agent)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-agent&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-agent)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-agent&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-agent)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-agent&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-agent)
+
+
+# Pico-Agent
+
+**[Pico-Agent](https://github.com/dperezcabrera/pico-agent)** is a lightweight, protocol-based framework for building modular AI agents using dependency injection.
+
+It eliminates the boilerplate of manually managing LLM chains, prompts, and tools. Instead, you declare **what** you want the agent to do using Python Protocols, and the framework handles **how** to execute it via **[Pico-IoC](https://github.com/dperezcabrera/pico-ioc)**.
+
+> 🤖 **Protocol-First Design**
+> 💉 **True Dependency Injection**
+> 🧠 **Smart Model Routing**
+> 🔄 **Multi-Agent Orchestration**
+> 🔌 **LLM Agnostic (LangChain based)**
+
+-----
+
+## 🎯 Why pico-agent?
+
+Most agent frameworks require you to instantiate classes, manually bind tools, and hardcode model names. Pico-Agent moves this complexity into the IoC container, promoting clean architecture and testability.
+
+| Feature | Standard Approach | Pico-Agent |
+|----------|-------------------|------------|
+| **Definition** | Concrete Classes / Functions | Python Protocols (Interfaces) |
+| **Discovery** | Manual Instantiation | Auto-scanning via IoC |
+| **Tools** | Manual Binding | DI Injection & Name Reference |
+| **Configuration** | Global Env Vars | Injected Configuration Components |
+| **Orchestration** | Complex Chains | Agents using Agents as Tools |
+
+-----
+
+## 🧱 Core Features
+
+  - **Declarative Agents:** Use `@agent` on standard `typing.Protocol`.
+  - **Capability Routing:** Request `FAST`, `SMART`, `CODING` capabilities instead of specific model names.
+  - **Auto-Discovery:** Leverages `pico-ioc` 2.2+ custom scanners to find agents automatically.
+  - **Type-Safe:** Full support for Pydantic input/output schemas.
+  - **ReAct Loops:** Built-in support for reasoning loops and tool usage.
+
+-----
+
+## 📦 Installation
+
+```bash
+pip install pico-agent
+```
+
+Install with specific provider support:
+
+```bash
+pip install "pico-agent[openai,google]"
+```
+
+-----
+
+## 🚀 Quick Example (with pico-stack)
+
+The best way to use `pico-agent` is with `pico-stack`, which handles auto-discovery out of the box.
+
+### 1\. Define the Agent Protocol
+
+The docstring becomes the system prompt. The method signature defines the tool input.
+
+```python
+from typing import Protocol
+from pico_agent import agent, AgentCapability, AgentType
+
+@agent(
+    name="translator",
+    capability=AgentCapability.FAST,  # Uses a faster/cheaper model
+    system_prompt="You are a professional translator.",
+    user_prompt_template="Translate this to Spanish: {text}",
+    agent_type=AgentType.ONE_SHOT
+)
+class TranslatorAgent(Protocol):
+    def translate(self, text: str) -> str: ...
+```
+
+### 2\. Configure Credentials
+
+Inject the centralized `LLMConfig` and set your keys. This avoids hardcoded environment variable lookups inside the library.
+
+```python
+import os
+from pico_ioc import component, configure
+from pico_agent import LLMConfig
+
+@component
+class AppConfig:
+    @configure
+    def setup_llm(self, config: LLMConfig):
+        # Load from Env, Vault, AWS Secrets, etc.
+        config.api_keys["openai"] = os.getenv("OPENAI_API_KEY")
+        config.api_keys["google"] = os.getenv("GOOGLE_API_KEY")
+```
+
+### 3\. Run the Application
+
+```python
+import src
+from pico_stack import init
+from app.agents import TranslatorAgent
+
+def main():
+    # Scans modules, finds agents, wires dependencies
+    container = init(src)
+
+    # Get your agent instance (auto-generated proxy)
+    translator = container.get(TranslatorAgent)
+
+    result = translator.translate(text="Dependency Injection is cool")
+    print(result) # "La inyección de dependencias es genial"
+
+if __name__ == "__main__":
+    main()
+```
+
+-----
+
+## 🛠 Advanced Usage
+
+### ReAct Agents & Tools
+
+Agents can use any dependency in the container as a tool.
+
+```python
+# 1. Define a tool (standard component)
+from pico_ioc import component
+
+@component
+class Calculator:
+    def add(self, a: int, b: int) -> int:
+        """Adds two numbers."""
+        return a + b
+
+# 2. Define the Agent
+@agent(
+    name="math_expert",
+    capability=AgentCapability.REASONING,
+    agent_type=AgentType.REACT,  # Enables Reasoning Loop
+    tools=["calculator"],        # Reference tool by name (snake_case of class)
+    max_iterations=5
+)
+class MathAgent(Protocol):
+    def solve(self, problem: str) -> str: ...
+```
+
+### Multi-Agent Orchestration
+
+An agent can use other agents as tools simply by referencing them.
+
+```python
+@agent(
+    name="orchestrator",
+    capability=AgentCapability.SMART,
+    system_prompt="Coordinate the sub-agents to solve the task.",
+    # Inject other agents as tools available to this LLM
+    agents=["translator", "math_expert"] 
+)
+class Orchestrator(Protocol):
+    def handle_request(self, task: str) -> str: ...
+```
+
+-----
+
+## ⚙️ Model Routing & Configuration
+
+`pico-agent` uses semantic capabilities to route to specific models. You can configure this globally using a configurer.
+
+```python
+from pico_ioc import component, configure
+from pico_agent.router import ModelRouter, AgentCapability
+
+@component
+class RouterConfig:
+    @configure
+    def configure_router(self, router: ModelRouter):
+        # Update default mappings
+        router.update_mapping(AgentCapability.FAST, "openai:gpt-5-mini")
+        router.update_mapping(AgentCapability.SMART, "anthropic:claude-4-5-sonnet")
+        
+        # You can also use "provider:model" syntax
+        router.update_mapping(AgentCapability.CODING, "deepseek:deepseek-coder")
+```
+
+-----
+
+## 🧪 Testing
+
+Testing is simple because you can mock the underlying `LLMFactory` or the agent protocol itself.
+
+```python
+from unittest.mock import MagicMock
+from pico_ioc import init
+from pico_agent import LLMFactory, LLM
+
+def test_my_agent():
+    mock_llm = MagicMock(spec=LLM)
+    mock_llm.invoke.return_value = "Mocked Response"
+    
+    mock_factory = MagicMock(spec=LLMFactory)
+    mock_factory.create.return_value = mock_llm
+    mock_factory.return_value = mock_factory # For singleton resolution
+
+    container = init(
+        modules=["pico_agent", "my_app"],
+        overrides={LLMFactory: mock_factory},
+        custom_scanners=[AgentScanner()] # If not using pico-stack
+    )
+    
+    agent = container.get(MyAgent)
+    assert agent.run("test") == "Mocked Response"
+```
+
+-----
+
+## 📝 License
+
+This project is licensed under the MIT License.

pico_agent-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=69.0", "wheel", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pico-agent"
+dynamic = ["version"]
+authors = [{ name = "David Perez Cabrera", email = "dperezcabrera@gmail.com" }]
+description = "A pico agent framework with LangChain integration."
+readme = { file = "pico.txt", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+keywords = [
+    "ioc", 
+    "di", 
+    "dependency injection", 
+    "agent", 
+    "llm", 
+    "langchain",
+    "ai"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+dependencies = [
+    "pico-ioc >= 2.2.0",
+    "pydantic>=2.0",
+    "langchain>=1.0.2",
+    "langchain-core",
+    "langchain-community",
+    "langchain-model-profiles",
+]
+
+[project.optional-dependencies]
+openai = ["langchain-openai"]
+google = ["langchain-google-genai"]
+anthropic = ["langchain-anthropic"]
+community = ["langchain-community"]
+all = [
+    "langchain-openai",
+    "langchain-google-genai",
+    "langchain-anthropic",
+    "langchain-community",
+]
+
+[project.urls]
+Homepage = "https://github.com/dperezcabrera/pico-agent"
+Repository = "https://github.com/dperezcabrera/pico-agent"
+"Issue Tracker" = "https://github.com/dperezcabrera/pico-agent/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["pico_agent*"]
+
+[tool.setuptools_scm]
+version_scheme = "post-release"
+local_scheme = "no-local-version"
+fallback_version = "0.1.0"
+write_to = "src/pico_agent/_version.py"
+write_to_template = "__version__ = '{version}'\n"
+
+[project.entry-points."pico_stack.modules"]
+pico_agent = "pico_agent"

pico_agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pico_agent-0.1.0/src/pico_agent/__init__.py

@@ -0,0 +1,31 @@
+from .config import AgentConfig, AgentType, AgentCapability, LLMConfig
+from .decorators import agent
+from .registry import AgentConfigService, ToolRegistry
+from .interfaces import CentralConfigClient, LLMFactory, LLM
+from .scanner import AgentScanner
+from .validation import AgentValidator, ValidationReport, ValidationIssue, Severity
+from .exceptions import AgentError, AgentDisabledError, AgentConfigurationError
+
+PICO_SCANNERS = [AgentScanner()]
+
+__all__ = [
+    "AgentConfig",
+    "LLMConfig",
+    "AgentType",
+    "AgentCapability",
+    "agent",
+    "AgentConfigService",
+    "ToolRegistry",
+    "CentralConfigClient",
+    "LLMFactory",
+    "LLM",
+    "AgentScanner",
+    "PICO_SCANNERS",
+    "AgentValidator",
+    "ValidationReport",
+    "ValidationIssue",
+    "Severity",
+    "AgentError",
+    "AgentDisabledError",
+    "AgentConfigurationError"
+]

pico_agent-0.1.0/src/pico_agent/_version.py

@@ -0,0 +1 @@
+__version__ = '0.1.0'

pico_agent-0.1.0/src/pico_agent/config.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict
+from enum import Enum
+
+class AgentType(str, Enum):
+    ONE_SHOT = "one_shot"
+    REACT = "react"
+
+class AgentCapability:
+    FAST = "fast"
+    SMART = "smart"
+    REASONING = "reasoning"
+    VISION = "vision"
+    CODING = "coding"
+
+@dataclass
+class AgentConfig:
+    name: str
+    system_prompt: str
+    user_prompt_template: str
+    capability: str = AgentCapability.SMART
+    enabled: bool = True
+    agent_type: AgentType = AgentType.ONE_SHOT
+    max_iterations: int = 5
+    tools: List[str] = field(default_factory=list)
+    agents: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+    tracing_enabled: bool = True
+    temperature: float = 0.7
+    max_tokens: Optional[int] = None
+    llm_profile: Optional[str] = None
+
+@dataclass
+class LLMConfig:
+    api_keys: Dict[str, str] = field(default_factory=dict)
+    base_urls: Dict[str, str] = field(default_factory=dict)

pico_agent-0.1.0/src/pico_agent/decorators.py

@@ -0,0 +1,42 @@
+from typing import List, Optional, Callable, Type
+from .config import AgentConfig, AgentType, AgentCapability
+
+AGENT_META_KEY = "_pico_agent_meta"
+IS_AGENT_INTERFACE = "_pico_is_agent_interface"
+
+def agent(
+    name: str,
+    capability: str = AgentCapability.SMART,
+    system_prompt: str = "",
+    user_prompt_template: str = "{input}",
+    agent_type: AgentType = AgentType.ONE_SHOT,
+    max_iterations: int = 5,
+    tools: Optional[List[str]] = None,
+    agents: Optional[List[str]] = None,
+    tags: Optional[List[str]] = None,
+    tracing_enabled: bool = True,
+    temperature: float = 0.7,
+    llm_profile: Optional[str] = None
+) -> Callable[[Type], Type]:
+
+    def decorator(cls_or_proto: Type) -> Type:
+        default_config = AgentConfig(
+            name=name,
+            capability=capability,
+            system_prompt=system_prompt,
+            user_prompt_template=user_prompt_template,
+            agent_type=agent_type,
+            max_iterations=max_iterations,
+            tools=tools or [],
+            agents=agents or [],
+            tags=tags or [],
+            tracing_enabled=tracing_enabled,
+            temperature=temperature,
+            llm_profile=llm_profile
+        )
+
+        setattr(cls_or_proto, AGENT_META_KEY, default_config)
+        setattr(cls_or_proto, IS_AGENT_INTERFACE, True)
+        return cls_or_proto
+
+    return decorator