percepto 0.1.dev40__py3-none-any.whl

percepto/__init__.py

@@ -0,0 +1,131 @@
+"""percepto — universal perception platform for AI agents.
+
+Usage::
+
+    import percepto
+
+    # Quick inference (auto-routes to best skill)
+    result = percepto.run("detect", source="image.jpg")
+
+    # Load a specific model
+    model = percepto.load("rtmdet-s", pretrained=True)
+
+    # Natural language routing
+    skill = percepto.understand("find objects in this image")
+
+    # List all capabilities
+    percepto.capabilities()
+
+    # High-level inference (direct)
+    det = percepto.Detector("rtmdet-s")
+    result = det("image.jpg")
+    result.save("output.jpg")
+"""
+
+# Register built-in skills
+from percepto._registry import register as _register
+from percepto._version import __version__
+from percepto.skills.detect import DetectionSkill
+
+_register(DetectionSkill())
+
+
+def run(skill_name: str, **kwargs):
+    """Run a perception skill by name.
+
+    Args:
+        skill_name: Skill name (e.g. 'detect').
+        **kwargs: Arguments passed to the skill's input schema.
+
+    Returns:
+        Structured output (Pydantic model).
+    """
+    from percepto._registry import get
+
+    skill = get(skill_name)
+    if not skill.is_loaded:
+        skill.load(
+            model=kwargs.pop("model", "auto"),
+            device=kwargs.pop("device", "auto"),
+        )
+    input_obj = skill.input_schema(**kwargs)
+    return skill.run(input_obj)
+
+
+def load(model_name: str, pretrained: bool = True, num_classes: int = 80, **kwargs):
+    """Load a detection model by name.
+
+    Args:
+        model_name: Model variant (e.g. 'rtmdet-s').
+        pretrained: Load pretrained weights.
+        num_classes: Number of classes.
+
+    Returns:
+        PyTorch nn.Module.
+    """
+    from percepto.skills.detect.models import load as _load_model
+
+    return _load_model(model_name, pretrained=pretrained, num_classes=num_classes, **kwargs)
+
+
+def available_models() -> list[str]:
+    """Return sorted list of all available detection model names."""
+    from percepto.skills.detect.models import available_models as _available_models
+
+    return _available_models()
+
+
+def understand(query: str):
+    """Route a natural language query to the best skill.
+
+    Args:
+        query: e.g. "find objects in this image"
+
+    Returns:
+        Best matching Skill instance, or None.
+    """
+    from percepto._router import SkillRouter
+
+    router = SkillRouter()
+    return router.route(query)
+
+
+def capabilities() -> dict[str, list[str]]:
+    """List all skills and their capabilities.
+
+    Returns:
+        Dict mapping skill names to their capability tags.
+    """
+    from percepto._registry import all_skills
+
+    return {name: skill.capabilities for name, skill in all_skills().items()}
+
+
+def compose(*steps):
+    """Create a validated pipeline from skill steps.
+
+    Args:
+        *steps: (skill_name, config_dict) tuples.
+
+    Returns:
+        Pipeline instance.
+    """
+    from percepto._compose import compose as _compose
+
+    return _compose(*steps)
+
+
+# Convenience re-exports for detection (most common use case)
+from percepto.skills.detect.inference.detect import Detection, Detector
+
+__all__ = [
+    "__version__",
+    "run",
+    "load",
+    "available_models",
+    "understand",
+    "capabilities",
+    "compose",
+    "Detection",
+    "Detector",
+]

percepto/_compose.py

@@ -0,0 +1,68 @@
+"""Pipeline composition — chain skills together with build-time validation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from percepto._registry import get
+from percepto._skill import Skill
+
+
+class Pipeline:
+    """A validated chain of skills that processes data sequentially."""
+
+    def __init__(self, steps: list[tuple[str, dict[str, Any]]]) -> None:
+        """Build and validate a pipeline.
+
+        Args:
+            steps: List of (skill_name, config_kwargs) tuples.
+
+        Raises:
+            ValueError: If skills don't exist.
+        """
+        self._steps: list[tuple[Skill, dict[str, Any]]] = []
+
+        for skill_name, kwargs in steps:
+            skill = get(skill_name)
+            self._steps.append((skill, kwargs))
+
+        self._validate_chain()
+
+    def _validate_chain(self) -> None:
+        """Validate the pipeline chain.
+
+        For Phase 3.0 with only detection, this is a basic check.
+        Full type compatibility validation comes when more skills are added.
+        """
+        if not self._steps:
+            msg = "Pipeline must have at least one step."
+            raise ValueError(msg)
+
+    def run(self, initial_input: BaseModel) -> BaseModel:
+        """Execute all steps sequentially."""
+        result = initial_input
+        for skill, kwargs in self._steps:
+            if not skill.is_loaded:
+                skill.load(**kwargs)
+            result = skill.run(result)
+        return result
+
+    @property
+    def steps(self) -> list[str]:
+        """Return skill names in order."""
+        return [skill.name for skill, _ in self._steps]
+
+
+def compose(*steps: tuple[str, dict[str, Any]]) -> Pipeline:
+    """Create a validated Pipeline from skill steps.
+
+    Usage::
+
+        pipe = compose(
+            ("detect", {"model": "rtmdet-l"}),
+        )
+        result = pipe.run(DetectionInput(source="image.jpg"))
+    """
+    return Pipeline(list(steps))

percepto/_hardware.py

@@ -0,0 +1,35 @@
+"""Hardware detection and model auto-selection."""
+
+from __future__ import annotations
+
+
+def resolve_auto_model(device: str = "auto") -> str:
+    """Pick a detection model based on available hardware.
+
+    Args:
+        device: Target device string or 'auto'.
+
+    Returns:
+        Model variant name (e.g. 'rtmdet-l', 'rtmdet-s', 'rtmdet-tiny').
+    """
+    import torch
+    from loguru import logger
+
+    has_cuda = torch.cuda.is_available() if device == "auto" else device.startswith("cuda")
+
+    if has_cuda:
+        try:
+            vram_mb = torch.cuda.get_device_properties(0).total_mem / (1024 * 1024)
+            if vram_mb >= 6000:
+                logger.debug("Auto model: cuda=True, vram={:.0f}MB -> rtmdet-l", vram_mb)
+                return "rtmdet-l"
+            if vram_mb >= 3000:
+                logger.debug("Auto model: cuda=True, vram={:.0f}MB -> rtmdet-s", vram_mb)
+                return "rtmdet-s"
+        except Exception:
+            pass
+        logger.debug("Auto model: cuda=True, vram=unknown -> rtmdet-s")
+        return "rtmdet-s"
+
+    logger.debug("Auto model: cuda=False -> rtmdet-tiny")
+    return "rtmdet-tiny"

percepto/_registry.py

@@ -0,0 +1,71 @@
+"""Skill registry — discover and manage perception skills."""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+
+from percepto._skill import Skill
+
+# Global skill registry
+_SKILLS: dict[str, Skill] = {}
+_discovered = False
+
+
+def register(skill: Skill) -> None:
+    """Explicitly register a skill instance."""
+    if not isinstance(skill, Skill):
+        msg = f"Expected a Skill, got {type(skill).__name__}"
+        raise TypeError(msg)
+    if skill.name in _SKILLS:
+        msg = f"Skill {skill.name!r} is already registered."
+        raise ValueError(msg)
+    _SKILLS[skill.name] = skill
+
+
+def get(name: str) -> Skill:
+    """Get a registered skill by name."""
+    _discover_entry_points()
+    if name not in _SKILLS:
+        available = sorted(_SKILLS.keys())
+        msg = f"Unknown skill: {name!r}. Available: {available}"
+        raise ValueError(msg)
+    return _SKILLS[name]
+
+
+def available_skills() -> list[str]:
+    """Return sorted list of registered skill names."""
+    _discover_entry_points()
+    return sorted(_SKILLS.keys())
+
+
+def all_skills() -> dict[str, Skill]:
+    """Return all registered skills."""
+    _discover_entry_points()
+    return dict(_SKILLS)
+
+
+def _discover_entry_points() -> None:
+    """Discover skills from 'percepto.skills' entry point group (lazy, once)."""
+    global _discovered  # noqa: PLW0603
+    if _discovered:
+        return
+    _discovered = True
+
+    eps = entry_points(group="percepto.skills")
+    for ep in eps:
+        if ep.name not in _SKILLS:
+            try:
+                skill_factory = ep.load()
+                skill = skill_factory()
+                register(skill)
+            except Exception:
+                from loguru import logger
+
+                logger.warning("Failed to load skill from entry point {!r} — skipping", ep.name)
+
+
+def _reset() -> None:
+    """Reset registry state (for testing only)."""
+    global _discovered  # noqa: PLW0603
+    _SKILLS.clear()
+    _discovered = False

percepto/_resolve.py

@@ -0,0 +1,120 @@
+"""Source resolution — handle file paths, URLs, and base64 image inputs."""
+
+from __future__ import annotations
+
+import base64
+import ipaddress
+import re
+import socket
+import tempfile
+from pathlib import Path
+from urllib.parse import urlparse
+
+from loguru import logger
+
+_BASE64_PATTERN = re.compile(r"^[A-Za-z0-9+/=]{100,}$")
+
+
+def resolve_source(source: str) -> Path:
+    """Resolve an image source to a local file path.
+
+    Handles three input types:
+    - File path: returned as-is (validated to exist)
+    - URL (http/https): downloaded to temp file with SSRF protection
+    - Base64: decoded to temp file
+
+    Args:
+        source: File path, URL, or base64-encoded image string.
+
+    Returns:
+        Path to the resolved image file.
+
+    Raises:
+        FileNotFoundError: If source is a file path that doesn't exist.
+        ValueError: If source is an invalid URL, blocked by SSRF protection,
+                    or invalid base64.
+        ConnectionError: If URL fetch fails.
+    """
+    # Check for data URI (data:image/png;base64,...)
+    if source.startswith("data:image/"):
+        return _decode_base64(source.split(",", 1)[1] if "," in source else source)
+
+    # Check for URL
+    if source.startswith(("http://", "https://")):
+        return _fetch_url(source)
+
+    # Check for raw base64 string
+    if _BASE64_PATTERN.match(source):
+        return _decode_base64(source)
+
+    # Treat as file path
+    path = Path(source)
+    if not path.exists():
+        msg = f"Image file not found: {source}"
+        raise FileNotFoundError(msg)
+    return path
+
+
+def _decode_base64(data: str) -> Path:
+    """Decode base64 image data to a temporary file."""
+    try:
+        raw = base64.b64decode(data)
+    except Exception as e:
+        msg = f"Invalid base64 image data: {e}"
+        raise ValueError(msg) from e
+
+    tmp = tempfile.NamedTemporaryFile(suffix=".jpg", delete=False)
+    tmp.write(raw)
+    tmp.close()
+    logger.debug("Decoded base64 image to {}", tmp.name)
+    return Path(tmp.name)
+
+
+def _fetch_url(url: str) -> Path:
+    """Download image from URL with SSRF protection."""
+    parsed = urlparse(url)
+    hostname = parsed.hostname
+
+    if not hostname:
+        msg = f"Invalid URL (no hostname): {url}"
+        raise ValueError(msg)
+
+    # Resolve hostname to IP and validate against SSRF
+    _validate_hostname(hostname)
+
+    # Download
+    try:
+        import urllib.request
+
+        tmp = tempfile.NamedTemporaryFile(suffix=".jpg", delete=False)
+        tmp.close()
+        urllib.request.urlretrieve(url, tmp.name)  # noqa: S310
+        logger.debug("Downloaded image from {} to {}", url, tmp.name)
+        return Path(tmp.name)
+    except Exception as e:
+        msg = f"Failed to download image from {url}: {e}"
+        raise ConnectionError(msg) from e
+
+
+def _validate_hostname(hostname: str) -> None:
+    """Validate hostname is not a private/reserved IP (SSRF protection).
+
+    Resolves the hostname via DNS and checks the resolved IP against
+    blocked ranges: private (RFC 1918), link-local, loopback, reserved.
+    """
+    try:
+        results = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
+    except socket.gaierror as e:
+        msg = f"Cannot resolve hostname: {hostname}"
+        raise ValueError(msg) from e
+
+    for family, _, _, _, sockaddr in results:
+        ip_str = sockaddr[0]
+        try:
+            ip = ipaddress.ip_address(ip_str)
+        except ValueError:
+            continue
+
+        if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved:
+            msg = f"URL blocked: {hostname} resolves to private/reserved IP {ip_str}"
+            raise ValueError(msg)

percepto/_router.py

@@ -0,0 +1,44 @@
+"""Smart Skill Router — maps natural language queries to skills."""
+
+from __future__ import annotations
+
+from percepto._registry import all_skills
+from percepto._skill import Skill
+
+
+class SkillRouter:
+    """Routes queries to the best matching skill using keyword matching.
+
+    Phase 1: keyword overlap scoring.
+    Future: swap in embedding-based matching without changing the interface.
+    """
+
+    def route(self, query: str) -> Skill | None:
+        """Find the best skill for a natural-language query.
+
+        Args:
+            query: e.g. "find objects in this image", "detect cars"
+
+        Returns:
+            Best matching Skill, or None if no match above threshold.
+        """
+        skills = all_skills()
+        if not skills:
+            return None
+
+        query_tokens = set(query.lower().split())
+        best_skill = None
+        best_score = 0
+
+        for skill in skills.values():
+            caps = set(skill.capabilities)
+            # Also include the skill name and words from description
+            caps.add(skill.name)
+            caps.update(skill.description.lower().split())
+
+            score = len(query_tokens & caps)
+            if score > best_score:
+                best_score = score
+                best_skill = skill
+
+        return best_skill if best_score > 0 else None

percepto/_skill.py

@@ -0,0 +1,91 @@
+"""Skill Protocol — the contract every perception skill implements."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+
+@runtime_checkable
+class Skill(Protocol):
+    """A perception skill that can be discovered, invoked, and composed.
+
+    Every skill declares:
+    - What it does (metadata for CLI/MCP auto-generation)
+    - What inputs it accepts (Pydantic schema)
+    - What outputs it produces (Pydantic schema)
+    - How to run it
+    """
+
+    @property
+    def name(self) -> str:
+        """Unique skill identifier, e.g. 'detect', 'segment', 'ocr'."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """Human-readable description for CLI help and MCP tool descriptions."""
+        ...
+
+    @property
+    def version(self) -> str:
+        """Skill version string."""
+        ...
+
+    @property
+    def input_schema(self) -> type[BaseModel]:
+        """Pydantic model class describing accepted inputs."""
+        ...
+
+    @property
+    def output_schema(self) -> type[BaseModel]:
+        """Pydantic model class describing outputs."""
+        ...
+
+    @property
+    def capabilities(self) -> list[str]:
+        """Tags describing what this skill can do. Used by the router.
+
+        Examples: ['detect', 'objects', 'bounding-boxes', 'coco']
+        """
+        ...
+
+    def load(self, model: str = "auto", device: str = "auto", **kwargs: Any) -> None:
+        """Load and prepare the underlying model. Called before run().
+
+        Args:
+            model: Model variant name or 'auto' for hardware-aware selection.
+            device: Target device.
+            **kwargs: Skill-specific configuration.
+        """
+        ...
+
+    @property
+    def is_loaded(self) -> bool:
+        """Whether the skill's model is loaded and ready."""
+        ...
+
+    def run(self, input: BaseModel) -> BaseModel:
+        """Execute the skill on validated input, returning structured output.
+
+        Args:
+            input: Validated input matching self.input_schema.
+
+        Returns:
+            Result matching self.output_schema.
+        """
+        ...
+
+    def available_models(self) -> list[str]:
+        """List model variants this skill supports."""
+        ...
+
+    @property
+    def cli_commands(self) -> dict[str, Any] | None:
+        """Optional: extra CLI commands this skill provides beyond run().
+
+        Returns a dict mapping command names to typer-compatible functions.
+        If None, the CLI auto-generates a single command from run().
+        """
+        ...

percepto/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.dev40'
+__version_tuple__ = version_tuple = (0, 1, 'dev40')
+
+__commit_id__ = commit_id = None