summonpot 0.1.0__py3-none-any.whl

summonpot/__init__.py

@@ -0,0 +1,12 @@
+"""summonpot — An API framework where every endpoint is an agent."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from summonpot.pot import Pot
+
+try:
+    __version__ = version("summonpot")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["Pot"]

summonpot/cli.py

@@ -0,0 +1,86 @@
+"""summonpot CLI — serve your Pot from the command line."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import sys
+from pathlib import Path
+
+import typer
+
+from summonpot.pot import Pot
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        from importlib.metadata import version
+
+        typer.echo(f"summonpot {version('summonpot')}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="summonpot",
+    help="An AI-native API framework. Every endpoint is an agent that runs automatically.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def main(
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """An API framework where every endpoint is an agent."""
+
+
+@app.command("serve")
+def serve_command(
+    source: str = typer.Argument(
+        ...,
+        help="Path to a Python file containing a Pot instance named 'pot'.",
+    ),
+    host: str = typer.Option("0.0.0.0", "--host", help="Host to bind to."),
+    port: int = typer.Option(8000, "--port", "-p", help="Port to bind to."),
+) -> None:
+    """Serve a Pot file as an HTTP API."""
+    pot = _load_pot(source)
+    typer.echo(f"Summoning {pot.name} on http://{host}:{port}")
+    pot.serve(host=host, port=port)
+
+
+def _load_pot(source: str) -> Pot:
+    """Load a Pot instance from a Python file."""
+    filepath = Path(source).resolve()
+    if not filepath.exists():
+        typer.echo(f"Error: file not found: {filepath}", err=True)
+        raise typer.Exit(1)
+
+    sys.path.insert(0, str(filepath.parent))
+    try:
+        spec = importlib.util.spec_from_file_location("_summonpot_user", filepath)
+        if spec is None or spec.loader is None:
+            typer.echo(f"Error: could not load module from {filepath}", err=True)
+            raise typer.Exit(1)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+    except Exception as e:
+        typer.echo(f"Error loading {filepath}: {e}", err=True)
+        raise typer.Exit(1) from None
+
+    pot = getattr(mod, "pot", None)
+    if pot is None:
+        typer.echo(
+            f"Error: no 'pot' variable found in {filepath}. "
+            "Define a Pot instance named 'pot'.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return pot

summonpot/models.py

@@ -0,0 +1,89 @@
+"""Data models for summonpot."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ParamDef:
+    """A single parameter of an endpoint or tool."""
+
+    name: str
+    type_annotation: str = "str"
+    description: str = ""
+    required: bool = True
+    default: Any = None
+
+
+@dataclass
+class ToolDef:
+    """A tool registered with summonpot."""
+
+    name: str
+    description: str
+    parameters: list[ParamDef] = field(default_factory=list)
+    fn: Any = None  # the callable
+
+    def to_openai_tool(self) -> dict:
+        """Serialize to an OpenAI-compatible tool definition."""
+        properties = {}
+        required = []
+        for p in self.parameters:
+            properties[p.name] = {
+                "type": _pytype_to_json(p.type_annotation),
+                "description": p.description,
+            }
+            if p.required:
+                required.append(p.name)
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required,
+                },
+            },
+        }
+
+    async def call(self, **kwargs: Any) -> Any:
+        """Execute the tool with the given arguments."""
+        if inspect.iscoroutinefunction(self.fn):
+            return await self.fn(**kwargs)
+        return self.fn(**kwargs)
+
+
+@dataclass
+class EndpointDef:
+    """A registered endpoint summoned behind a route."""
+
+    path: str
+    name: str
+    description: str  # docstring = system prompt
+    parameters: list[ParamDef] = field(default_factory=list)
+    return_type: str = "str"
+    tools: list[ToolDef] = field(default_factory=list)
+    stream: bool = False
+    model: str | None = None
+
+
+def _pytype_to_json(type_str: str) -> str:
+    """Map a Python type name to a JSON schema type."""
+    mapping = {
+        "str": "string",
+        "int": "integer",
+        "float": "number",
+        "bool": "boolean",
+        "dict": "object",
+        "list": "array",
+        "Any": "string",
+        "None": "null",
+    }
+    # Handle Optional[str] etc. — just take the first non-None type
+    cleaned = type_str.replace("Optional[", "").replace("]", "")
+    return mapping.get(cleaned, "string")

summonpot/pot.py

@@ -0,0 +1,192 @@
+"""Pot — the summoning vessel. Register endpoints, summon agents."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from summonpot.models import EndpointDef, ParamDef
+from summonpot.runtime import Runtime
+from summonpot.tools import build_tool_from_func
+
+
+class Pot:
+    """A summoning vessel for agentic endpoints.
+
+    Example::
+
+        from summonpot import Pot
+
+        pot = Pot(tools=[search_web])
+
+        @pot.summon("/research")
+        def research_topic(query: str) -> str:
+            \"\"\"Research this topic thoroughly.\"\"\"
+
+        pot.serve()
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        tools: list | None = None,
+    ) -> None:
+        self.name = name or "summonpot"
+        # Convert any raw functions to ToolDef objects
+        self._pot_tools: list = []
+        if tools:
+            for t in tools:
+                if hasattr(t, "to_openai_tool"):
+                    self._pot_tools.append(t)
+                else:
+                    self._pot_tools.append(build_tool_from_func(t))
+        self._endpoints: list[EndpointDef] = []
+        self._runtime = Runtime()
+
+    def __repr__(self) -> str:
+        return f"Pot({self.name!r}, endpoints={len(self._endpoints)}, tools={len(self._pot_tools)})"
+
+    def summon(
+        self,
+        path: str,
+        *,
+        tools: list | None = None,
+        stream: bool = False,
+        model: str | None = None,
+        method: str = "POST",
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Decorator: summon an agent behind the given route.
+
+        Args:
+            path: URL path for the endpoint (e.g. ``/research``).
+            tools: Additional tools specific to this endpoint.
+            stream: Whether to stream the response.
+            model: LLM model override for this endpoint.
+            method: HTTP method (default POST).
+        """
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            endpoint_name = func.__name__
+            description = inspect.getdoc(func) or ""
+
+            # Merge pot-level tools with endpoint-specific tools
+            all_tools = list(self._pot_tools)
+            if tools:
+                # Convert raw functions to ToolDefs
+                for t in tools:
+                    if not hasattr(t, "to_openai_tool"):
+                        all_tools.append(build_tool_from_func(t))
+                    else:
+                        all_tools.append(t)
+
+            # Extract parameters from function signature
+            sig = inspect.signature(func)
+            hints = _safe_get_type_hints(func)
+            parameters: list[ParamDef] = []
+            for pname, param in sig.parameters.items():
+                if pname in ("self", "cls"):
+                    continue
+                type_str = _get_type_str(pname, param, hints)
+                is_required = param.default is inspect.Parameter.empty
+                parameters.append(
+                    ParamDef(
+                        name=pname,
+                        type_annotation=type_str,
+                        description="",
+                        required=is_required,
+                        default=None if is_required else param.default,
+                    )
+                )
+
+            # Return type
+            return_hint = hints.get("return", sig.return_annotation)
+            if return_hint is inspect.Parameter.empty or return_hint is None:
+                return_type = "str"
+            elif hasattr(return_hint, "__name__"):
+                return_type = return_hint.__name__
+            else:
+                return_type = str(return_hint)
+
+            endpoint = EndpointDef(
+                path=path,
+                name=endpoint_name,
+                description=description,
+                parameters=parameters,
+                return_type=return_type,
+                tools=all_tools,
+                stream=stream,
+                model=model,
+            )
+            self._endpoints.append(endpoint)
+            return func
+
+        return decorator
+
+    @property
+    def endpoints(self) -> list[EndpointDef]:
+        """Return all registered endpoints."""
+        return list(self._endpoints)
+
+    def serve(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 8000,
+    ) -> None:
+        """Serve endpoints as an HTTP API.
+
+        Starts a FastAPI + uvicorn server.
+        Requires the ``serve`` extra: ``pip install summonpot[serve]``
+        """
+        self._serve_api(host, port)
+
+    def _serve_api(self, host: str, port: int) -> None:
+        try:
+            import uvicorn
+        except ImportError:
+            raise ModuleNotFoundError(
+                "uvicorn and fastapi are required for serving. "
+                "Install with: pip install summonpot[serve]"
+            ) from None
+
+        from summonpot.server import build_app
+
+        app = build_app(self)
+        uvicorn.run(app, host=host, port=port)  # type: ignore[arg-type]
+
+
+def _get_type_str(
+    pname: str,
+    param: inspect.Parameter,
+    hints: dict[str, Any],
+) -> str:
+    if pname in hints:
+        return _type_name(hints[pname])
+    if param.annotation is not inspect.Parameter.empty:
+        return _type_name(param.annotation)
+    return "str"
+
+
+def _type_name(tp: Any) -> str:
+    if hasattr(tp, "__origin__"):
+        origin = tp.__origin__
+        args = tp.__args__
+        if origin is list and args:
+            return f"list[{_type_name(args[0])}]"
+        if origin is dict and len(args) >= 2:
+            return f"dict[{_type_name(args[0])}, {_type_name(args[1])}]"
+        if origin is tuple:
+            return f"tuple[{', '.join(_type_name(a) for a in args)}]"
+        return _type_name(origin)
+    if tp is type(None):
+        return "None"
+    if hasattr(tp, "__name__"):
+        return tp.__name__
+    return str(tp)
+
+
+def _safe_get_type_hints(func: Callable[..., Any]) -> dict[str, Any]:
+    try:
+        return inspect.get_annotations(func, eval_str=True)
+    except Exception:
+        return inspect.get_annotations(func, eval_str=False)

summonpot/runtime.py

@@ -0,0 +1,150 @@
+"""Agent runtime — owns the LLM call loop for summonpot."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from summonpot.models import EndpointDef
+
+
+class Runtime:
+    """Agent execution engine.
+
+    Calls an OpenAI-compatible API to fulfill an endpoint's intent.
+    In v0.1 this is a single LLM call with function calling (no multi-step loop).
+    The loop will deepen in v0.2+.
+    """
+
+    def __init__(self) -> None:
+        self.api_key = os.environ.get("SUMMONPOT_API_KEY") or os.environ.get(
+            "OPENAI_API_KEY", ""
+        )
+        self.base_url = os.environ.get(
+            "SUMMONPOT_BASE_URL",
+            os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
+        )
+        self.default_model = os.environ.get("SUMMONPOT_MODEL", "gpt-4o-mini")
+
+    async def call(
+        self,
+        endpoint: EndpointDef,
+        params: dict[str, Any],
+    ) -> Any:
+        """Execute an endpoint's agentic logic with the given parameters.
+
+        Builds the LLM request, calls the API, and returns the structured result.
+        """
+        if not self.api_key:
+            raise RuntimeError(
+                "No API key configured. Set SUMMONPOT_API_KEY or OPENAI_API_KEY."
+            )
+
+        model = endpoint.model or self.default_model
+        system_prompt = endpoint.description
+
+        # Build the user message — describe what the caller wants
+        user_message = self._build_user_message(endpoint, params)
+
+        # Build tool definitions for function calling
+        tools = [t.to_openai_tool() for t in endpoint.tools]
+
+        # Build the request body
+        body: dict[str, Any] = {
+            "model": model,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_message},
+            ],
+        }
+
+        if endpoint.return_type.lower() in ("str", "string"):
+            # Plain text response — no structured output enforcement
+            pass
+        elif endpoint.return_type in ("dict", "object", "Any"):
+            body["response_format"] = {"type": "json_object"}
+        else:
+            # For typed responses, try to use structured outputs
+            body["response_format"] = {"type": "json_object"}
+
+        if tools:
+            body["tools"] = tools
+            body["tool_choice"] = "auto"
+
+        # Make the API call
+        import httpx
+
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            response = await client.post(
+                f"{self.base_url}/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                },
+                json=body,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+        message = data["choices"][0]["message"]
+
+        # Handle tool calls
+        if message.get("tool_calls"):
+            for tc in message["tool_calls"]:
+                tool_name = tc["function"]["name"]
+                tool_args = json.loads(tc["function"]["arguments"])
+                # Find the matching tool and execute it
+                for t in endpoint.tools:
+                    if t.name == tool_name:
+                        tool_result = await t.call(**tool_args)
+                        # Append tool result to messages
+                        body["messages"].append(message)
+                        body["messages"].append(
+                            {
+                                "role": "tool",
+                                "tool_call_id": tc["id"],
+                                "content": json.dumps(tool_result, default=str),
+                            }
+                        )
+                        break
+
+            # Get final response after tool calls
+            body.pop("tools", None)
+            body.pop("tool_choice", None)
+            async with httpx.AsyncClient(timeout=120.0) as client:
+                response = await client.post(
+                    f"{self.base_url}/chat/completions",
+                    headers={
+                        "Authorization": f"Bearer {self.api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    json=body,
+                )
+                response.raise_for_status()
+                data = response.json()
+            message = data["choices"][0]["message"]
+
+        content = message.get("content", "")
+
+        # Parse structured output if needed
+        if endpoint.return_type.lower() not in ("str", "string", "any"):
+            try:
+                return json.loads(content)
+            except (json.JSONDecodeError, TypeError):
+                return content
+
+        return content
+
+    def _build_user_message(
+        self,
+        endpoint: EndpointDef,
+        params: dict[str, Any],
+    ) -> str:
+        """Build a user message from the endpoint's parameters."""
+        parts = [f"Endpoint: {endpoint.path}"]
+        if params:
+            parts.append("Parameters:")
+            for key, value in params.items():
+                parts.append(f"  {key}: {json.dumps(value, default=str)}")
+        return "\n".join(parts)

summonpot/server.py

@@ -0,0 +1,106 @@
+"""HTTP server for summonpot — builds FastAPI routes from endpoints."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from summonpot import __version__
+
+if TYPE_CHECKING:
+    from summonpot.pot import Pot
+
+
+def build_app(pot: Pot) -> Any:
+    """Build a FastAPI application from a Pot instance."""
+    from fastapi import FastAPI
+
+    app = FastAPI(
+        title=pot.name,
+        description="An AI-native API framework. Every endpoint is an agent that runs automatically.",
+        version=__version__,
+    )
+
+    for endpoint in pot.endpoints:
+        route_path = endpoint.path
+        method = "POST"
+
+        if endpoint.parameters:
+            from pydantic import create_model
+
+            fields: dict[str, tuple[type, Any]] = {}
+            for p in endpoint.parameters:
+                field_type = _str_to_type(p.type_annotation)
+                if p.required:
+                    fields[p.name] = (field_type, ...)
+                else:
+                    fields[p.name] = (field_type, p.default)
+
+            RequestModel = create_model(
+                f"{endpoint.name}Request",
+                **fields,  # pyright: ignore[reportArgumentType, reportCallIssue]
+            )
+
+            # Use a unique module-level attribute so FastAPI/Pydantic can resolve it
+            import sys as _sys
+
+            _attr = f"_RouteModel_{id(RequestModel)}"
+            setattr(_sys.modules[__name__], _attr, RequestModel)
+
+            # Resolve the model for the closure
+            resolved_model = RequestModel
+
+            async def _handle_with_body(
+                body: resolved_model,  # type: ignore[valid-type]
+                _ep=endpoint,
+                _pt=pot,
+            ) -> Any:
+                params = body.model_dump() if hasattr(body, "model_dump") else body
+                return await _pt._runtime.call(_ep, params)
+
+            _handle_with_body.__annotations__["body"] = resolved_model
+
+            app.add_api_route(
+                route_path,
+                _handle_with_body,
+                methods=[method],
+                summary=(
+                    endpoint.description.split("\n")[0]
+                    if endpoint.description
+                    else endpoint.name
+                ),
+                description=endpoint.description,
+            )
+        else:
+
+            async def _handle_without_body(ep=endpoint, pt=pot) -> Any:
+                return await pt._runtime.call(ep, {})
+
+            app.add_api_route(
+                route_path,
+                _handle_without_body,
+                methods=[method],
+                summary=(
+                    endpoint.description.split("\n")[0]
+                    if endpoint.description
+                    else endpoint.name
+                ),
+                description=endpoint.description,
+            )
+
+    return app
+
+
+def _str_to_type(type_str: str) -> type:
+    """Convert a type annotation string to a Python type."""
+    mapping: dict[str, type] = {
+        "str": str,
+        "int": int,
+        "float": float,
+        "bool": bool,
+        "list": list,
+        "dict": dict,
+        "Any": str,
+        "None": type(None),
+    }
+    base = type_str.split("[")[0].split("|")[0].strip()
+    return mapping.get(base, str)

summonpot/tools.py

@@ -0,0 +1,125 @@
+"""Tool registration and built-in tools for summonpot."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from summonpot.models import ParamDef, ToolDef
+
+
+def tool(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Callable[[Callable[..., Any]], ToolDef]:
+    """Decorator to define a summonpot tool from a plain function.
+
+    Example::
+
+        from summonpot.tools import tool
+
+        @tool(name="search_web", description="Search the web for information")
+        def search_web(query: str) -> list[dict]:
+            \"\"\"Search the web.\"\"\"
+            return [{"title": "result"}]
+    """
+
+    def decorator(func: Callable[..., Any]) -> ToolDef:
+        tool_name = name or func.__name__
+        tool_desc = description or inspect.getdoc(func) or ""
+        sig = inspect.signature(func)
+        hints = _safe_get_type_hints(func)
+        params: list[ParamDef] = []
+        for pname, param in sig.parameters.items():
+            if pname in ("self", "cls"):
+                continue
+            type_str = _get_type_str(pname, param, hints)
+            is_required = param.default is inspect.Parameter.empty
+            description_text = ""
+            # Try to get param description from docstring
+            params.append(
+                ParamDef(
+                    name=pname,
+                    type_annotation=type_str,
+                    description=description_text,
+                    required=is_required,
+                    default=None if is_required else param.default,
+                )
+            )
+        return ToolDef(
+            name=tool_name,
+            description=tool_desc,
+            parameters=params,
+            fn=func,
+        )
+
+    return decorator
+
+
+def build_tool_from_func(func: Callable[..., Any]) -> ToolDef:
+    """Build a ToolDef from a raw function (no decorator)."""
+    tool_name = func.__name__
+    tool_desc = inspect.getdoc(func) or ""
+    sig = inspect.signature(func)
+    hints = _safe_get_type_hints(func)
+    params: list[ParamDef] = []
+    for pname, param in sig.parameters.items():
+        if pname in ("self", "cls"):
+            continue
+        type_str = _get_type_str(pname, param, hints)
+        is_required = param.default is inspect.Parameter.empty
+        params.append(
+            ParamDef(
+                name=pname,
+                type_annotation=type_str,
+                description="",
+                required=is_required,
+                default=None if is_required else param.default,
+            )
+        )
+    return ToolDef(
+        name=tool_name,
+        description=tool_desc,
+        parameters=params,
+        fn=func,
+    )
+
+
+def _get_type_str(
+    pname: str,
+    param: inspect.Parameter,
+    hints: dict[str, Any],
+) -> str:
+    if pname in hints:
+        return _type_name(hints[pname])
+    if param.annotation is not inspect.Parameter.empty:
+        return _type_name(param.annotation)
+    return "str"
+
+
+def _type_name(tp: Any) -> str:
+    """Convert a type annotation to a short string name."""
+    if hasattr(tp, "__origin__"):
+        origin = tp.__origin__
+        args = tp.__args__
+        if origin is list and args:
+            return f"list[{_type_name(args[0])}]"
+        if origin is dict and len(args) >= 2:
+            return f"dict[{_type_name(args[0])}, {_type_name(args[1])}]"
+        if origin is tuple:
+            return f"tuple[{', '.join(_type_name(a) for a in args)}]"
+        return _type_name(origin)
+    if tp is type(None):
+        return "None"
+    if hasattr(tp, "__name__"):
+        return tp.__name__
+    return str(tp)
+
+
+def _safe_get_type_hints(func: Callable[..., Any]) -> dict[str, Any]:
+    try:
+        return inspect.get_annotations(func, eval_str=True)
+    except Exception:
+        return inspect.get_annotations(func, eval_str=False)

summonpot-0.1.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: summonpot
+Version: 0.1.0
+Summary: An AI-native API framework. Every endpoint is an agent that runs automatically.
+Project-URL: Homepage, https://github.com/tugrulguner/summonpot
+Project-URL: Repository, https://github.com/tugrulguner/summonpot
+Project-URL: Issues, https://github.com/tugrulguner/summonpot/issues
+Project-URL: Changelog, https://github.com/tugrulguner/summonpot/blob/main/CHANGELOG.md
+Author: Tugrul Guner
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,agentic,ai,api,django,fastapi,framework,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: typer>=0.9.0; extra == 'all'
+Requires-Dist: uvicorn>=0.20.0; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: typer>=0.9.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.390; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: towncrier>=25.8.0; extra == 'dev'
+Requires-Dist: typer>=0.9.0; extra == 'dev'
+Requires-Dist: uvicorn>=0.20.0; extra == 'dev'
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.100.0; extra == 'serve'
+Requires-Dist: uvicorn>=0.20.0; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# summonpot
+
+<p align="center">
+  <img src="summonpot.png" alt="SummonPot" width="600">
+</p>
+
+[![CI](https://github.com/tugrulguner/summonpot/actions/workflows/ci.yml/badge.svg)](https://github.com/tugrulguner/summonpot/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/summonpot)](https://pypi.org/project/summonpot/)
+[![Python versions](https://img.shields.io/pypi/pyversions/summonpot)](https://pypi.org/project/summonpot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**An AI-native API framework. Every endpoint is an agent that runs automatically.**
+
+summonpot is a **full API framework** — with routing, validation, middleware, and serving — but built for the era where APIs don't just respond, they reason. Define routes. The framework runs the agents. No agent configuration. No framework ontology. Just endpoints that think.
+
+You define routes with a function signature, a docstring, and tools. The framework owns the agentic runtime — the LLM call loop, tool orchestration, structured output, and streaming. You don't configure an agent. You define an endpoint. The agent is summoned.
+
+```python
+from summonpot import Pot
+
+pot = Pot("my-service", tools=[search_web])
+
+@pot.summon("/research")
+def research_topic(query: str, depth: str = "standard") -> str:
+    """Research this topic thoroughly and return a comprehensive report."""
+
+@pot.summon("/analyze")
+def analyze_sentiment(text: str) -> dict:
+    """Analyze the text and return a JSON object with sentiment and topics."""
+
+pot.serve()
+```
+
+Call it like any API:
+
+```bash
+curl -X POST http://localhost:8000/research \
+  -H "Content-Type: application/json" \
+  -d '{"query": "quantum computing", "depth": "deep"}'
+```
+
+Behind the scenes, an agent runs — it thinks, uses tools, calls the LLM, enforces structured output, and returns the result. But you never wrote an agent. You wrote a route.
+
+## Why another framework?
+
+Every existing approach to building agentic APIs has the same problem: you first learn an agent framework (LangChain, CrewAI, AutoGen), then bolt an HTTP server on top. The mental model is "configure an agent" — which is complex, brittle, and framework-y.
+
+summonpot flips this: the **web framework IS the agent framework**. The routing is the agentic logic. The decorator is the incantation. The framework owns the smart parts.
+
+| | Existing frameworks | summonpot |
+|---|---|---|
+| Mental model | "Configure an agent" | "Define an endpoint" |
+| Surface area | Large (chains, agents, tools, memory, callbacks...) | Tiny (decorator + types + docstring) |
+| API exposure | Bolt-on HTTP wrapper | Native (routing IS the agent) |
+| Complexity | User manages the loop | Framework owns the loop, user provides intent |
+| Testability | Heavy mocking required | Test like a regular HTTP endpoint |
+| Onboarding | Learn the framework's ontology | If you know HTTP, you know this |
+
+## Installation
+
+```bash
+pip install summonpot            # core
+pip install summonpot[serve]     # + HTTP server (FastAPI/uvicorn)
+pip install summonpot[cli]       # + Typer CLI
+pip install summonpot[all]       # everything
+```
+
+You also need an OpenAI-compatible API key:
+
+```bash
+export SUMMONPOT_API_KEY=sk-...          # or OPENAI_API_KEY
+export SUMMONPOT_MODEL=gpt-4o-mini        # optional, default gpt-4o-mini
+export SUMMONPOT_BASE_URL=https://api.openai.com/v1   # optional
+```
+
+## Quick Start
+
+Create a file `app.py`:
+
+```python
+from summonpot import Pot
+
+# A tool available to every endpoint
+def search_web(query: str) -> list[dict]:
+    """Search the web for information."""
+    return [{"query": query, "result": "..."}]
+
+pot = Pot("my-service", tools=[search_web])
+
+@pot.summon("/research")
+def research_topic(query: str, depth: str = "standard") -> str:
+    """Research this topic thoroughly and return a comprehensive report."""
+
+@pot.summon("/summarize")
+def summarize(text: str) -> str:
+    """Summarize the given text into key bullet points."""
+
+@pot.summon("/analyze")
+def analyze_sentiment(text: str) -> dict:
+    """Analyze the text and return a JSON object with sentiment and topics."""
+```
+
+Serve it:
+
+```bash
+summonpot serve app.py                  # serves on 0.0.0.0:8000
+summonpot serve app.py --port 9000
+```
+
+Or from Python:
+
+```python
+pot.serve()                             # 0.0.0.0:8000
+pot.serve(host="127.0.0.1", port=9000)
+```
+
+## The Summoning Model
+
+| Concept | As summoning |
+|---|---|
+| Route definition | "At this path, I summon..." |
+| Docstring | The incantation (system prompt) |
+| Tools | Ingredients placed in the circle |
+| Parameters | What the summoner brings |
+| Return type | What appears |
+| `stream=True` | You asked it to speak continuously |
+
+## How it works
+
+summonpot inspects your endpoint function:
+
+- **Docstring** → becomes the system prompt the agent follows
+- **Parameters** → become the JSON request schema (validated by Pydantic)
+- **Return type** → becomes the output contract (structured JSON for non-`str` types)
+- **Tools** → exposed to the agent via function calling, so it can act, not just answer
+
+The framework owns the LLM call loop, tool orchestration, and structured-output enforcement. You provide intent — the endpoint.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `SUMMONPOT_API_KEY` | `OPENAI_API_KEY` | API key for the LLM provider |
+| `SUMMONPOT_BASE_URL` | `OPENAI_BASE_URL` or `https://api.openai.com/v1` | OpenAI-compatible endpoint |
+| `SUMMONPOT_MODEL` | `gpt-4o-mini` | Default model for all endpoints |
+
+Per-endpoint overrides:
+
+```python
+@pot.summon("/research", model="gpt-4o", stream=True)
+def research_topic(query: str) -> str:
+    """Research this topic."""
+```
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/tugrulguner/summonpot.git
+cd summonpot
+uv sync --all-extras
+```
+
+```bash
+make check    # lint + typecheck + test
+make lint     # ruff check + format check
+make test     # pytest
+make format   # auto-format
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for pull-request and single-source release instructions.
+
+## License
+
+MIT

summonpot-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+summonpot/__init__.py,sha256=Pr4MRN_1Dw3xNieTL2xx_Q08cYyBXdAMi3tO87z8CeQ,291
+summonpot/cli.py,sha256=Wvev2Ik7SYND9dV50z5Bsmf_vZ-fR-n5uykrGexayr8,2408
+summonpot/models.py,sha256=K2JrPGB_hvNmUyomxM5PTj4HvaHCYNbptaotmzH7w8A,2429
+summonpot/pot.py,sha256=HgNU6GbwuK7foMR0DXUh4NTBsJ-uNBtVeyou5NLtrJ8,6153
+summonpot/runtime.py,sha256=tIVzw374mA_jXFVVgPFKFDQL6z5beP35FTV-kGWJ-Qs,5270
+summonpot/server.py,sha256=beL8W1PwZYBdLF3hb5KNk8OP58RC6PjHeBf67NjG6-E,3279
+summonpot/tools.py,sha256=PiKaafCVSnAJ2asOcFy9DbLgYN3YkGcdDYk2WSUyCr8,3880
+summonpot-0.1.0.dist-info/METADATA,sha256=eE3RZETfNK6DVEbJez_Mo_w55Fg_zEkmtvAlt_d2JZ0,8168
+summonpot-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+summonpot-0.1.0.dist-info/entry_points.txt,sha256=leA2JLXJckzzm73eCDCmEAjcgQN2OLpffpdL8M4HthY,48
+summonpot-0.1.0.dist-info/licenses/LICENSE,sha256=RMhMT4PHyQK019lq5As5W0qclDwaFF59uSkoui8hyVg,1069
+summonpot-0.1.0.dist-info/RECORD,,

summonpot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

summonpot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+summonpot = summonpot.cli:app

summonpot-0.1.0.dist-info/licenses/LICENSE

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