pico-agent 0.1.0__py3-none-any.whl

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/_version.py

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

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/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

pico_agent/exceptions.py

@@ -0,0 +1,9 @@
+class AgentError(Exception):
+    pass
+
+class AgentDisabledError(AgentError):
+    def __init__(self, agent_name: str):
+        super().__init__(f"Agent '{agent_name}' is disabled via configuration.")
+
+class AgentConfigurationError(AgentError):
+    pass

pico_agent/factory.py

@@ -0,0 +1,65 @@
+from typing import Optional, Any
+from pico_ioc import factory, provides, component
+from .interfaces import CentralConfigClient, LLMFactory
+from .config import AgentConfig, LLMConfig
+from .registry import AgentConfigService, ToolRegistry, LocalAgentRegistry
+from .proxy import DynamicAgentProxy
+from .router import ModelRouter
+from .providers import LangChainLLMFactory
+
+class NoOpCentralClient(CentralConfigClient):
+    def get_agent_config(self, name: str) -> Optional[AgentConfig]: return None
+    def upsert_agent_config(self, config: AgentConfig) -> None: pass
+
+@factory
+class AgentInfrastructureFactory:
+    @provides(CentralConfigClient, scope="singleton")
+    def provide_central_config(self) -> CentralConfigClient: 
+        return NoOpCentralClient()
+    
+    @provides(LLMConfig, scope="singleton")
+    def provide_llm_config(self) -> LLMConfig:
+        return LLMConfig()
+
+    @provides(LLMFactory, scope="singleton")
+    def provide_llm_factory(self, config: LLMConfig) -> LLMFactory:
+        return LangChainLLMFactory(config)
+
+@component
+class DynamicProxyFactory:
+    def __init__(
+        self,
+        config_service: AgentConfigService,
+        tool_registry: ToolRegistry,
+        llm_factory: LLMFactory,
+        local_registry: LocalAgentRegistry,
+        model_router: ModelRouter
+    ):
+        self.config_service = config_service
+        self.tool_registry = tool_registry
+        self.llm_factory = llm_factory
+        self.local_registry = local_registry
+        self.model_router = model_router
+
+    def get_agent(self, name: str) -> Optional[Any]:
+        protocol = self.local_registry.get_protocol(name)
+        if protocol:
+            return self.create_proxy(protocol)
+        return None
+
+    def create_proxy(self, protocol: type) -> Any:
+        from .decorators import AGENT_META_KEY
+        config = getattr(protocol, AGENT_META_KEY)
+        
+        self.local_registry.register_default(config.name, config)
+        self.local_registry.register_protocol(config.name, protocol)
+        
+        return DynamicAgentProxy(
+            agent_name=config.name,
+            protocol_cls=protocol,
+            config_service=self.config_service,
+            tool_registry=self.tool_registry,
+            llm_factory=self.llm_factory,
+            model_router=self.model_router,
+            agent_resolver=self
+        )

pico_agent/interceptor.py

@@ -0,0 +1,25 @@
+from typing import Any, Callable
+from pico_ioc import component, MethodInterceptor, MethodCtx
+from .proxy import TracedAgentProxy
+from .decorators import AGENT_META_KEY
+
+@component
+class AgentInterceptor(MethodInterceptor):
+    def __init__(self, proxy: TracedAgentProxy):
+        self.proxy = proxy
+
+    def invoke(self, ctx: MethodCtx, call_next: Callable[[MethodCtx], Any]) -> Any:
+        config = getattr(ctx.cls, AGENT_META_KEY, None)
+        
+        if not config or ctx.name != "invoke":
+            return call_next(ctx)
+
+        user_input = ""
+        if ctx.args:
+            user_input = str(ctx.args[0])
+        elif "input" in ctx.kwargs:
+            user_input = str(ctx.kwargs["input"])
+        elif "message" in ctx.kwargs:
+            user_input = str(ctx.kwargs["message"])
+
+        return self.proxy.execute_agent(config.name, user_input)

pico_agent/interfaces.py

@@ -0,0 +1,14 @@
+from typing import Protocol, Any, List, Dict, Optional, Type
+from .config import AgentConfig
+
+class CentralConfigClient(Protocol):
+    def get_agent_config(self, name: str) -> Optional[AgentConfig]: ...
+    def upsert_agent_config(self, config: AgentConfig) -> None: ...
+
+class LLM(Protocol):
+    def invoke(self, messages: List[Dict[str, str]], tools: List[Any]) -> str: ...
+    def invoke_structured(self, messages: List[Dict[str, str]], tools: List[Any], output_schema: Type[Any]) -> Any: ...
+    def invoke_agent_loop(self, messages: List[Dict[str, str]], tools: List[Any], max_iterations: int, output_schema: Optional[Type[Any]] = None) -> Any: ...
+
+class LLMFactory(Protocol):
+    def create(self, model_name: str, temperature: float, max_tokens: Optional[int], llm_profile: Optional[str] = None) -> LLM: ...

pico_agent/providers.py

@@ -0,0 +1,210 @@
+import os
+from typing import List, Dict, Any, Type, Optional
+from langchain_core.messages import SystemMessage, HumanMessage, BaseMessage, AIMessage
+from langchain_core.language_models.chat_models import BaseChatModel
+from .interfaces import LLM, LLMFactory
+from .config import LLMConfig
+
+class LangChainAdapter(LLM):
+    def __init__(self, chat_model: BaseChatModel):
+        self.model = chat_model
+
+    def _convert_messages(self, messages: List[Dict[str, str]]) -> List[BaseMessage]:
+        lc_messages = []
+        for msg in messages:
+            if msg["role"] == "system":
+                lc_messages.append(SystemMessage(content=msg["content"]))
+            elif msg["role"] == "user":
+                lc_messages.append(HumanMessage(content=msg["content"]))
+            elif msg["role"] == "assistant":
+                lc_messages.append(AIMessage(content=msg["content"]))
+        return lc_messages
+
+    def invoke(self, messages: List[Dict[str, str]], tools: List[Any]) -> str:
+        lc_messages = self._convert_messages(messages)
+        model_with_tools = self.model
+        
+        if tools:
+            model_with_tools = self.model.bind_tools(tools)
+        
+        response = model_with_tools.invoke(lc_messages)
+        return str(response.content)
+
+    def invoke_structured(
+        self, 
+        messages: List[Dict[str, str]], 
+        tools: List[Any], 
+        output_schema: Type[Any]
+    ) -> Any:
+        lc_messages = self._convert_messages(messages)
+        structured_model = self.model.with_structured_output(output_schema)
+        return structured_model.invoke(lc_messages)
+
+    def invoke_agent_loop(
+        self, 
+        messages: List[Dict[str, str]], 
+        tools: List[Any], 
+        max_iterations: int, 
+        output_schema: Optional[Type[Any]] = None
+    ) -> Any:
+        from langgraph.prebuilt import create_react_agent
+        
+        lc_messages = self._convert_messages(messages)
+        agent_executor = create_react_agent(self.model, tools=tools)
+        
+        inputs = {"messages": lc_messages}
+        result = agent_executor.invoke(inputs, config={"recursion_limit": max_iterations})
+        
+        final_message = result["messages"][-1]
+        
+        if output_schema:
+             structured_model = self.model.with_structured_output(output_schema)
+             return structured_model.invoke([HumanMessage(content=str(final_message.content))])
+        
+        return str(final_message.content)
+
+class LangChainLLMFactory(LLMFactory):
+    def __init__(self, config: LLMConfig):
+        self.config = config
+
+    def create(self, model_name: str, temperature: float, max_tokens: Optional[int], llm_profile: Optional[str] = None) -> LLM:
+        final_provider = None
+        real_model_name = model_name
+
+        if ":" in model_name:
+            parts = model_name.split(":", 1)
+            final_provider = parts[0]
+            real_model_name = parts[1]
+        
+        if not final_provider:
+            final_provider = self._detect_provider(real_model_name)
+
+        chat_model = self.create_chat_model(final_provider, real_model_name, llm_profile)
+        
+        if temperature is not None:
+             try:
+                 chat_model.temperature = temperature
+             except AttributeError:
+                 pass
+        
+        if max_tokens is not None:
+             try:
+                 chat_model.max_tokens = max_tokens
+             except AttributeError:
+                 pass
+                 
+        return LangChainAdapter(chat_model)
+
+    def _get_api_key(self, provider: str, profile: Optional[str]) -> Optional[str]:
+        if profile and profile in self.config.api_keys:
+            return self.config.api_keys[profile]
+        return self.config.api_keys.get(provider)
+
+    def _get_base_url(self, provider: str, default: Optional[str], profile: Optional[str]) -> Optional[str]:
+        if profile and profile in self.config.base_urls:
+            return self.config.base_urls[profile]
+        return self.config.base_urls.get(provider, default)
+
+    def _detect_provider(self, model_name: str) -> str:
+        name_lower = model_name.lower()
+        if "gemini" in name_lower: return "gemini"
+        elif "claude" in name_lower or "anthropic" in name_lower: return "claude"
+        elif "deepseek" in name_lower: return "deepseek"
+        elif "qwen" in name_lower: return "qwen"
+        elif "azure" in name_lower: return "azure"
+        return "openai"
+
+    def create_chat_model(self, provider: str, model_name: str, profile: Optional[str]) -> BaseChatModel:
+        provider_lower = provider.lower()
+        timeout = 60
+        
+        def require_key(p_name, key_val):
+            if not key_val:
+                raise ValueError(
+                    f"API Key not found for provider '{p_name}' (Profile: '{profile}'). "
+                    "Please configure it via LLMConfig."
+                )
+            return key_val
+        
+        if provider_lower == "openai":
+            try:
+                from langchain_openai import ChatOpenAI
+                api_key = require_key("openai", self._get_api_key("openai", profile))
+                return ChatOpenAI(model=model_name, api_key=api_key, request_timeout=timeout)
+            except ImportError:
+                raise ImportError("Please install 'pico-agent[openai]' to use this provider.")
+                
+        elif provider_lower == "azure":
+            try:
+                from langchain_openai import AzureChatOpenAI
+                import os
+                api_key = require_key("azure", self._get_api_key("azure", profile))
+                return AzureChatOpenAI(
+                    azure_deployment=model_name,
+                    openai_api_version=os.getenv("AZURE_OPENAI_API_VERSION"), 
+                    api_key=api_key,
+                    request_timeout=timeout,
+                )
+            except ImportError:
+                raise ImportError("Please install 'pico-agent[openai]' to use Azure OpenAI.")
+
+        elif provider_lower == "gemini" or provider_lower == "google":
+            try:
+                from langchain_google_genai import ChatGoogleGenerativeAI
+                api_key = require_key("google", self._get_api_key("google", profile))
+                return ChatGoogleGenerativeAI(
+                    model=model_name,
+                    google_api_key=api_key,
+                    temperature=0.0,
+                    request_timeout=timeout,
+                )
+            except ImportError:
+                raise ImportError("Please install 'pico-agent[google]' to use Gemini.")
+
+        elif provider_lower == "claude" or provider_lower == "anthropic":
+            try:
+                from langchain_anthropic import ChatAnthropic
+                api_key = require_key("anthropic", self._get_api_key("anthropic", profile))
+                base_url = self._get_base_url("anthropic", None, profile)
+                return ChatAnthropic(
+                    model=model_name, 
+                    api_key=api_key,
+                    base_url=base_url,
+                    temperature=0.0, 
+                    default_request_timeout=timeout
+                )
+            except ImportError:
+                raise ImportError("Please install 'pico-agent[anthropic]' to use Claude.")
+
+        elif provider_lower == "deepseek":
+            try:
+                from langchain_openai import ChatOpenAI
+                base_url = self._get_base_url("deepseek", "https://api.deepseek.com/v1", profile)
+                api_key = require_key("deepseek", self._get_api_key("deepseek", profile))
+                return ChatOpenAI(
+                    model=model_name,
+                    base_url=base_url,
+                    api_key=api_key,
+                    temperature=0.0,
+                    request_timeout=timeout,
+                )
+            except ImportError:
+                raise ImportError("Please install 'pico-agent[openai]' to use DeepSeek.")
+
+        elif provider_lower == "qwen":
+            try:
+                from langchain_openai import ChatOpenAI
+                base_url = self._get_base_url("qwen", "https://dashscope.aliyuncs.com/compatible-mode/v1", profile)
+                api_key = require_key("qwen", self._get_api_key("qwen", profile))
+                return ChatOpenAI(
+                    model=model_name,
+                    base_url=base_url,
+                    api_key=api_key,
+                    temperature=0.0,
+                    request_timeout=timeout,
+                )
+            except ImportError:
+                raise ImportError("Please install 'pico-agent[openai]' to use Qwen.")
+
+        else:
+            raise ValueError(f"Unknown LLM Provider: {provider}")

pico_agent/proxy.py

@@ -0,0 +1,234 @@
+import inspect
+from typing import Any, List, Dict, Type, get_type_hints, Optional
+from pydantic import BaseModel
+from pico_ioc import component
+from .config import AgentConfig, AgentType
+from .registry import AgentConfigService, ToolRegistry
+from .interfaces import LLMFactory
+from .router import ModelRouter
+from .exceptions import AgentDisabledError
+from .tools import AgentAsTool
+
+@component
+class TracedAgentProxy:
+    def __init__(
+        self,
+        config_service: AgentConfigService,
+        tool_registry: ToolRegistry,
+        llm_factory: LLMFactory,
+        model_router: ModelRouter
+    ):
+        self.config_service = config_service
+        self.tool_registry = tool_registry
+        self.llm_factory = llm_factory
+        self.model_router = model_router
+
+    def execute_agent(self, agent_name: str, user_input: str) -> Any:
+        config = self.config_service.get_config(agent_name)
+        
+        if not config.enabled:
+            raise AgentDisabledError(agent_name)
+        
+        final_model_name = self.model_router.resolve_model(
+            capability=config.capability,
+            runtime_override=None
+        )
+        
+        llm = self.llm_factory.create(
+            model_name=final_model_name,
+            temperature=config.temperature,
+            max_tokens=config.max_tokens,
+            llm_profile=config.llm_profile
+        )
+
+        resolved_tools = []
+        for tool_name in config.tools:
+            t = self.tool_registry.get_tool(tool_name)
+            if t:
+                resolved_tools.append(t)
+        
+        dynamic = self.tool_registry.get_dynamic_tools(config.tags)
+        for dt in dynamic:
+            if dt not in resolved_tools:
+                resolved_tools.append(dt)
+
+        messages = []
+        if config.system_prompt:
+            messages.append({"role": "system", "content": config.system_prompt})
+        
+        messages.append({"role": "user", "content": user_input})
+        
+        if config.agent_type == AgentType.REACT:
+            return llm.invoke_agent_loop(
+                messages, 
+                resolved_tools, 
+                config.max_iterations
+            )
+        else:
+            return llm.invoke(messages, resolved_tools)
+
+
+class DynamicAgentProxy:
+    def __init__(
+        self,
+        agent_name: str,
+        protocol_cls: Type,
+        config_service: AgentConfigService,
+        tool_registry: ToolRegistry,
+        llm_factory: LLMFactory,
+        model_router: ModelRouter,
+        agent_resolver: Any = None 
+    ):
+        self.agent_name = agent_name
+        self.protocol_cls = protocol_cls
+        self.config_service = config_service
+        self.tool_registry = tool_registry
+        self.llm_factory = llm_factory
+        self.model_router = model_router
+        self.agent_resolver = agent_resolver
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+             raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
+        if not hasattr(self.protocol_cls, name):
+            raise AttributeError(f"Agent {self.agent_name} has no method {name}")
+        
+        method_ref = getattr(self.protocol_cls, name)
+
+        if not callable(method_ref):
+            return method_ref
+        
+        method_sig = inspect.signature(method_ref)
+        
+        params = list(method_sig.parameters.values())
+        if params and params[0].name == "self":
+            new_params = params[1:]
+            method_sig = method_sig.replace(parameters=new_params)
+
+        type_hints = get_type_hints(method_ref)
+        return_type = type_hints.get("return", str)
+
+        def method_wrapper(*args, **kwargs):
+            input_context = self._extract_input_context(method_sig, args, kwargs)
+            runtime_model = kwargs.pop("model", kwargs.pop("_model", None))
+            return self._execute(input_context, return_type, runtime_model)
+        
+        return method_wrapper
+
+    def _extract_input_context(self, sig: inspect.Signature, args: tuple, kwargs: dict) -> Dict[str, Any]:
+        bound = sig.bind(*args, **kwargs)
+        bound.apply_defaults()
+        context = {}
+        for name, val in bound.arguments.items():
+            if name in ("model", "_model", "self"): 
+                continue
+            context[name] = str(val)
+        return context
+
+    def _execute(self, input_context: Dict[str, Any], return_type: Type, runtime_model: Optional[str]) -> Any:
+        config = self.config_service.get_config(self.agent_name)
+        
+        if not config.enabled:
+            raise AgentDisabledError(self.agent_name)
+        
+        final_model_name = self.model_router.resolve_model(
+            capability=config.capability,
+            runtime_override=runtime_model
+        )
+        
+        llm = self.llm_factory.create(
+            model_name=final_model_name,
+            temperature=config.temperature,
+            max_tokens=config.max_tokens,
+            llm_profile=config.llm_profile
+        )
+
+        resolved_tools = self._resolve_dependencies(config)
+        messages = self._build_messages(config, input_context)
+        
+        target_schema = return_type if self._is_pydantic_model(return_type) else None
+
+        if config.agent_type == AgentType.REACT:
+            return llm.invoke_agent_loop(
+                messages, 
+                resolved_tools, 
+                config.max_iterations, 
+                output_schema=target_schema
+            )
+        else:
+            if target_schema:
+                return llm.invoke_structured(messages, resolved_tools, target_schema)
+            return llm.invoke(messages, resolved_tools)
+
+    def _resolve_dependencies(self, config: AgentConfig) -> List[Any]:
+        final_tools = []
+        
+        for tool_name in config.tools:
+            t = self.tool_registry.get_tool(tool_name)
+            if t:
+                final_tools.append(t)
+
+        if self.agent_resolver:
+            for agent_name in config.agents:
+                try:
+                    child_agent = self.agent_resolver.get_agent(agent_name)
+                    if child_agent:
+                        child_config = self.config_service.get_config(agent_name)
+                        if not child_config.enabled:
+                            continue
+                        
+                        method_name = "invoke"
+                        protocol = child_agent.protocol_cls
+                        candidates = [
+                            n for n, m in inspect.getmembers(protocol)
+                            if not n.startswith("_") and (inspect.isfunction(m) or inspect.ismethod(m))
+                        ]
+                        
+                        if "invoke" in candidates:
+                            method_name = "invoke"
+                        elif candidates:
+                            method_name = candidates[0]
+                        
+                        adapter = AgentAsTool(
+                            agent_proxy=child_agent, 
+                            method_name=method_name, 
+                            description=f"Delegates to agent: {agent_name}"
+                        )
+                        final_tools.append(adapter)
+                except Exception:
+                    pass
+
+        dynamic = self.tool_registry.get_dynamic_tools(config.tags)
+        for dt in dynamic:
+            if dt not in final_tools:
+                final_tools.append(dt)
+        
+        return final_tools
+
+    def _build_messages(self, config: AgentConfig, input_context: Dict[str, Any]) -> List[Dict[str, str]]:
+        messages = []
+        if config.system_prompt:
+            try:
+                sys_content = config.system_prompt.format(**input_context)
+            except KeyError:
+                sys_content = config.system_prompt
+            messages.append({"role": "system", "content": sys_content})
+        
+        user_content = ""
+        if config.user_prompt_template:
+            try:
+                user_content = config.user_prompt_template.format(**input_context)
+            except KeyError:
+                user_content = " ".join(input_context.values())
+        else:
+            user_content = " ".join(input_context.values())
+        
+        messages.append({"role": "user", "content": user_content})
+        return messages
+
+    def _is_pydantic_model(self, cls: Type) -> bool:
+        try:
+            return issubclass(cls, BaseModel)
+        except TypeError:
+            return False

pico_agent/registry.py

@@ -0,0 +1,77 @@
+from typing import Dict, Any, Optional, List
+from pico_ioc import component
+from .config import AgentConfig
+from .interfaces import CentralConfigClient
+
+@component
+class ToolRegistry:
+    def __init__(self):
+        self._tools: Dict[str, Any] = {}
+        self._tag_map: Dict[str, List[str]] = {}
+
+    def register(self, name: str, tool: Any, tags: List[str] = []) -> None:
+        self._tools[name] = tool
+        for tag in tags:
+            if tag not in self._tag_map:
+                self._tag_map[tag] = []
+            self._tag_map[tag].append(name)
+
+    def get_tool(self, name: str) -> Optional[Any]:
+        return self._tools.get(name)
+
+    def get_dynamic_tools(self, agent_tags: List[str]) -> List[Any]:
+        found_tools = []
+        for tag in agent_tags:
+            tool_names = self._tag_map.get(tag, [])
+            for name in tool_names:
+                t = self._tools.get(name)
+                if t and t not in found_tools:
+                    found_tools.append(t)
+        
+        global_names = self._tag_map.get("global", [])
+        for name in global_names:
+            t = self._tools.get(name)
+            if t and t not in found_tools:
+                found_tools.append(t)
+        return found_tools
+
+@component
+class LocalAgentRegistry:
+    def __init__(self):
+        self._defaults: Dict[str, AgentConfig] = {}
+        self._protocols: Dict[str, type] = {}
+
+    def register_default(self, name: str, config: AgentConfig) -> None:
+        self._defaults[name] = config
+
+    def register_protocol(self, name: str, protocol: type) -> None:
+        self._protocols[name] = protocol
+
+    def get_default(self, name: str) -> Optional[AgentConfig]:
+        return self._defaults.get(name)
+
+    def get_protocol(self, name: str) -> Optional[type]:
+        return self._protocols.get(name)
+
+@component
+class AgentConfigService:
+    def __init__(self, central_client: CentralConfigClient, local_registry: LocalAgentRegistry):
+        self.central_client = central_client
+        self.local_registry = local_registry
+        self.auto_register = True
+
+    def get_config(self, name: str) -> AgentConfig:
+        remote_config = self.central_client.get_agent_config(name)
+        if remote_config:
+            return remote_config
+        
+        local_config = self.local_registry.get_default(name)
+        if not local_config:
+            raise ValueError(f"No configuration found for agent: {name}")
+
+        if self.auto_register:
+            try:
+                self.central_client.upsert_agent_config(local_config)
+            except Exception:
+                pass
+        return local_config

pico_agent/router.py

@@ -0,0 +1,23 @@
+from typing import Dict, Optional
+from pico_ioc import component
+from .config import AgentCapability
+
+@component(scope="singleton")
+class ModelRouter:
+    def __init__(self):
+        self._capability_map: Dict[str, str] = {
+            AgentCapability.FAST: "gpt-5-mini",
+            AgentCapability.SMART: "gpt-5.1",
+            AgentCapability.REASONING: "gemini-3-pro",
+            AgentCapability.VISION: "gpt-4o",
+            AgentCapability.CODING: "claude-3-5-sonnet"
+        }
+
+    def resolve_model(self, capability: str, runtime_override: Optional[str] = None) -> str:
+        if runtime_override:
+            return runtime_override
+            
+        return self._capability_map.get(capability, "gpt-5.1")
+
+    def update_mapping(self, capability: str, model: str) -> None:
+        self._capability_map[capability] = model

pico_agent/scanner.py

@@ -0,0 +1,37 @@
+from typing import Any, Optional, Tuple, Callable
+from pico_ioc.factory import DeferredProvider, ProviderMetadata
+from .decorators import IS_AGENT_INTERFACE, AGENT_META_KEY
+
+class AgentScanner:
+    def should_scan(self, obj: Any) -> bool:
+        return isinstance(obj, type) and getattr(obj, IS_AGENT_INTERFACE, False)
+
+    def scan(self, obj: Any) -> Optional[Tuple[Any, Callable[[], Any], ProviderMetadata]]:
+        if not self.should_scan(obj):
+            return None
+
+        config = getattr(obj, AGENT_META_KEY)
+
+        def builder(container, locator):
+            from .factory import DynamicProxyFactory
+            factory = container.get(DynamicProxyFactory)
+            return factory.create_proxy(obj)
+
+        provider = DeferredProvider(builder)
+
+        metadata = ProviderMetadata(
+            key=obj,
+            provided_type=obj,
+            concrete_class=None,
+            factory_class=None,
+            factory_method=None,
+            qualifiers=set(),
+            primary=True,
+            lazy=True,
+            infra="pico_agent",
+            pico_name=config.name,
+            scope="singleton",
+            dependencies=()
+        )
+
+        return (obj, provider, metadata)

pico_agent/tools.py

@@ -0,0 +1,30 @@
+import inspect
+from typing import Any, Type, get_type_hints
+from pydantic import BaseModel, create_model
+
+class AgentAsTool:
+    def __init__(self, agent_proxy: Any, method_name: str = "invoke", description: str = ""):
+        self.proxy = agent_proxy
+        self.method_name = method_name
+        self._func = getattr(agent_proxy, method_name)
+        self.name = getattr(agent_proxy, "agent_name", "agent_tool")
+        self.description = description or f"Agent {self.name}"
+        self.args_schema = self._create_schema_from_sig()
+
+    def _create_schema_from_sig(self) -> Type[BaseModel]:
+        protocol_cls = self.proxy.protocol_cls
+        real_method = getattr(protocol_cls, self.method_name)
+        sig = inspect.signature(real_method)
+        type_hints = get_type_hints(real_method)
+        
+        fields = {}
+        for param_name, param in sig.parameters.items():
+            if param_name == "self": continue
+            annotation = type_hints.get(param_name, str)
+            default = param.default if param.default is not inspect.Parameter.empty else ...
+            fields[param_name] = (annotation, default)
+            
+        return create_model(f"{self.name}Input", **fields)
+
+    def __call__(self, **kwargs):
+        return self._func(**kwargs)

pico_agent/validation.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass, field
+from typing import List
+from enum import Enum
+from .config import AgentConfig
+
+class Severity(str, Enum):
+    WARNING = "warning"
+    ERROR = "error"
+
+@dataclass
+class ValidationIssue:
+    field: str
+    message: str
+    severity: Severity
+
+@dataclass
+class ValidationReport:
+    valid: bool
+    issues: List[ValidationIssue] = field(default_factory=list)
+
+    @property
+    def has_errors(self) -> bool:
+        return any(i.severity == Severity.ERROR for i in self.issues)
+
+class AgentValidator:
+    def validate(self, config: AgentConfig) -> ValidationReport:
+        issues = []
+
+        if not config.name or len(config.name.strip()) == 0:
+            issues.append(ValidationIssue("name", "Agent name cannot be empty", Severity.ERROR))
+        
+        if not config.capability:
+            issues.append(ValidationIssue("capability", "Agent capability must be defined", Severity.ERROR))
+        
+        if not (0.0 <= config.temperature <= 2.0):
+            issues.append(ValidationIssue("temperature", "Temperature must be between 0.0 and 2.0", Severity.ERROR))
+        elif config.temperature > 1.0:
+            issues.append(ValidationIssue("temperature", "High temperature (>1.0) may cause hallucinations", Severity.WARNING))
+
+        if not config.system_prompt:
+            issues.append(ValidationIssue("system_prompt", "System prompt is empty", Severity.WARNING))
+
+        return ValidationReport(valid=not any(i.severity == Severity.ERROR for i in issues), issues=issues)

pico_agent-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+pico_agent/__init__.py,sha256=jkQz7FcUSys_qVJTVIhzGy3QT0brZ4mmIKbT5T3YPpQ,855
+pico_agent/_version.py,sha256=IMjkMO3twhQzluVTo8Z6rE7Eg-9U79_LGKMcsWLKBkY,22
+pico_agent/config.py,sha256=pgFd5hSjsm6OOmReNDhCLTf0GpJO5z4zEQSjMgfxc6g,992
+pico_agent/decorators.py,sha256=Lv90ywOcfPrWcc4jQGrg00dWo3l_lv8ZhhwJa66p4ig,1372
+pico_agent/exceptions.py,sha256=dLHWRLw2cwV1Vfd7G5_24X7VWOVoyc0bOl8gH2GdEc8,252
+pico_agent/factory.py,sha256=2bv5mYahUgrxFYHbiS2ME0O2Mi938HBQWtQqypI4Kyo,2353
+pico_agent/interceptor.py,sha256=R3pPVQ5w0eK7woOMecbARYuJsfGycTOgMI_Ne-ntJ3A,861
+pico_agent/interfaces.py,sha256=VMpndZ0xOM9SkwRxE0sodBLw0Q3rKMSreZWhl6wu4Es,815
+pico_agent/providers.py,sha256=ygwmF7BXVb6dMxgS-4zSp-AWZgP36zDdYMO3-_auAsY,8748
+pico_agent/proxy.py,sha256=MvCZOp5VMMUXduHW-nb8NISpwXMS4AHI_PEzGRbC5Uo,8523
+pico_agent/registry.py,sha256=VmX-VlUIMRk_qSjmKWnJ4yjMRxOi60xQAww02hLNmw0,2630
+pico_agent/router.py,sha256=qkq5LpfWtVjxTyARSld8xKhehHvJ9qCx8obi53zVGqc,837
+pico_agent/scanner.py,sha256=oTsMXv0qkS9Utn3D0IFP8oH7cm8XZ6pSWB1GY1Q18Iw,1209
+pico_agent/tools.py,sha256=9N9vLslVK_azoBKPO6tKI0cxigMudBNazjcoiMFGxoU,1278
+pico_agent/validation.py,sha256=u2VykzguXwEoyjANj_GJxAJjoLO0WEwq3JjhAKCjMc4,1530
+pico_agent-0.1.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_agent-0.1.0.dist-info/METADATA,sha256=pFgiMwTtuhiP1C5xvVI04evWM53kfzHi7bvoJhmdJV8,3002
+pico_agent-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_agent-0.1.0.dist-info/entry_points.txt,sha256=Fs4uuKo-WNNDpU7i9MqxgjTDuZUELcsMjz-O9da4jM8,45
+pico_agent-0.1.0.dist-info/top_level.txt,sha256=0t60mhJrPdkaG6tyfJwHc1FIZ83BjB_Hz_eEPpZNc3E,11
+pico_agent-0.1.0.dist-info/RECORD,,

pico_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pico_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pico_stack.modules]
+pico_agent = pico_agent

pico_agent-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+pico_agent