neutron-framework 0.1.0__py3-none-any.whl

neutron/__init__.py

@@ -0,0 +1,72 @@
+"""Neutron — The AI application development framework for Python."""
+
+from neutron.app import App
+from neutron.config import NeutronConfig
+from neutron.depends import Depends
+from neutron.error import (
+    AppError,
+    bad_request,
+    conflict,
+    forbidden,
+    internal_error,
+    not_found,
+    rate_limited,
+    unauthorized,
+    validation_error,
+)
+from neutron.handler import Form, Header, Query, UploadFile
+from neutron.auth.csrf import CSRFMiddleware
+from neutron.middleware import (
+    CORSMiddleware,
+    CompressionMiddleware,
+    LoggingMiddleware,
+    OTelMiddleware,
+    RateLimitMiddleware,
+    RequestIDMiddleware,
+    TimeoutMiddleware,
+    TrailingSlashMiddleware,
+    default_stack,
+)
+from neutron.openapi import (
+    SecurityScheme,
+    api_key_scheme,
+    bearer_auth_scheme,
+    oauth2_scheme,
+)
+from neutron.router import Router
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "App",
+    "Router",
+    "Depends",
+    "Query",
+    "Header",
+    "Form",
+    "UploadFile",
+    "NeutronConfig",
+    "AppError",
+    "bad_request",
+    "not_found",
+    "unauthorized",
+    "forbidden",
+    "conflict",
+    "validation_error",
+    "rate_limited",
+    "internal_error",
+    "CSRFMiddleware",
+    "CORSMiddleware",
+    "CompressionMiddleware",
+    "LoggingMiddleware",
+    "OTelMiddleware",
+    "RateLimitMiddleware",
+    "RequestIDMiddleware",
+    "TimeoutMiddleware",
+    "TrailingSlashMiddleware",
+    "default_stack",
+    "SecurityScheme",
+    "bearer_auth_scheme",
+    "api_key_scheme",
+    "oauth2_scheme",
+]

neutron/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the Neutron CLI via ``python -m neutron``."""
+
+from neutron.cli import main
+
+main()

neutron/ai/__init__.py

@@ -0,0 +1,39 @@
+"""Neutron AI — first-class AI primitives for application development."""
+
+from neutron.ai.agent import Agent, AgentResult, handoff
+from neutron.ai.mcp import MCPClient, MCPServer
+from neutron.ai.memory import Memory, MemoryMessage
+from neutron.ai.providers import LLM, LLMResponse
+from neutron.ai.rag import RAGAnswer, RAGPipeline, RAGSource
+from neutron.ai.structured import extract_structured
+from neutron.ai.tools import Tool, tool
+from neutron.ai.workflow import Workflow, WorkflowResult, step
+
+__all__ = [
+    # Providers
+    "LLM",
+    "LLMResponse",
+    # Tools
+    "Tool",
+    "tool",
+    # Structured output
+    "extract_structured",
+    # Agents
+    "Agent",
+    "AgentResult",
+    "handoff",
+    # RAG
+    "RAGPipeline",
+    "RAGAnswer",
+    "RAGSource",
+    # Workflows
+    "Workflow",
+    "WorkflowResult",
+    "step",
+    # Memory
+    "Memory",
+    "MemoryMessage",
+    # MCP
+    "MCPServer",
+    "MCPClient",
+]

neutron/ai/agent.py

@@ -0,0 +1,205 @@
+"""Agent framework — tool loops, multi-turn, and handoffs."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, cast
+
+from pydantic import BaseModel
+
+from neutron.ai.providers import LLM, LLMResponse, Message
+from neutron.ai.tools import Tool, resolve_tool_call
+
+
+class AgentResult(BaseModel):
+    content: str
+    messages: list[dict[str, Any]] = []
+    tool_calls_made: int = 0
+
+
+class Agent:
+    """Base agent with tool use and multi-turn conversation.
+
+    Subclass and add tools via the ``@tool`` decorator::
+
+        class MyAgent(Agent):
+            llm = LLM(provider="openai", model="gpt-4o")
+            system_prompt = "You are a helpful assistant."
+
+            @tool
+            async def search(self, query: str) -> str:
+                \"\"\"Search the knowledge base.\"\"\"
+                ...
+
+        agent = MyAgent()
+        result = await agent.run("Find info about quantum computing")
+    """
+
+    llm: LLM | None = None
+    system_prompt: str = "You are a helpful assistant."
+    max_turns: int = 20
+
+    def __init__(
+        self,
+        llm: LLM | None = None,
+        db: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        if llm is not None:
+            self.llm = llm
+        self.db = db
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+        # Collect tools from class methods decorated with @tool
+        self._tools: list[Tool] = []
+        for attr_name in dir(self.__class__):
+            attr = getattr(self.__class__, attr_name, None)
+            if isinstance(attr, Tool):
+                # Bind self to the tool function
+                _fn = attr.fn
+                _self = self
+                bound_fn = lambda _fn=_fn, _self=_self, **kw: _fn(_self, **kw)
+                bound_tool = Tool(bound_fn, name=attr.name)
+                bound_tool.description = attr.description
+                bound_tool.schema = attr.schema
+                bound_tool.is_async = attr.is_async
+                self._tools.append(bound_tool)
+
+        # Also collect handoff tools
+        for attr_name in dir(self):
+            attr = getattr(self, attr_name, None)
+            if isinstance(attr, _HandoffTool):
+                self._tools.append(attr.as_tool())
+
+    async def run(
+        self,
+        prompt: str,
+        *,
+        messages: list[Message] | None = None,
+        tools: list[Tool] | None = None,
+    ) -> AgentResult:
+        """Run the agent loop until the LLM produces a final response."""
+        if self.llm is None:
+            raise ValueError("Agent requires an LLM. Set llm class attribute or pass to __init__.")
+
+        all_tools: list[Tool | Callable[..., Any]] = list(self._tools)
+        if tools:
+            all_tools.extend(tools)
+
+        conversation: list[Message] = list(messages or [])
+        if self.system_prompt:
+            conversation.insert(0, {"role": "system", "content": self.system_prompt})
+        conversation.append({"role": "user", "content": prompt})
+
+        total_tool_calls = 0
+
+        for _turn in range(self.max_turns):
+            response = await self.llm.chat(conversation, tools=all_tools)
+
+            if not response.tool_calls:
+                # Final response — no more tool calls
+                conversation.append(
+                    {"role": "assistant", "content": response.content}
+                )
+                return AgentResult(
+                    content=response.content,
+                    messages=conversation,
+                    tool_calls_made=total_tool_calls,
+                )
+
+            # Process tool calls
+            # Add assistant message with tool calls
+            conversation.append(
+                {
+                    "role": "assistant",
+                    "content": response.content or "",
+                    "tool_calls": [
+                        {
+                            "id": tc["id"],
+                            "type": "function",
+                            "function": {
+                                "name": tc["name"],
+                                "arguments": json.dumps(tc["arguments"]),
+                            },
+                        }
+                        for tc in response.tool_calls
+                    ],
+                }
+            )
+
+            for tc in response.tool_calls:
+                total_tool_calls += 1
+                tool_obj = resolve_tool_call(all_tools, tc["name"], tc["arguments"])
+                if tool_obj is None:
+                    tool_result = f"Error: Unknown tool '{tc['name']}'"
+                else:
+                    try:
+                        result = await tool_obj(**tc["arguments"])
+                        tool_result = (
+                            json.dumps(result) if not isinstance(result, str) else result
+                        )
+                    except Exception as e:
+                        tool_result = f"Error: {e}"
+
+                conversation.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tc["id"],
+                        "content": tool_result,
+                    }
+                )
+
+        # Max turns reached
+        return AgentResult(
+            content="Max turns reached without a final response.",
+            messages=conversation,
+            tool_calls_made=total_tool_calls,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Handoffs
+# ---------------------------------------------------------------------------
+
+
+class _HandoffTool:
+    """Marker for agent handoff methods."""
+
+    def __init__(self, target_cls: type[Any], fn: Any) -> None:
+        self.target_cls = target_cls
+        self.fn = fn
+        self.name = fn.__name__
+        self.description = (fn.__doc__ or "").strip()
+
+    def as_tool(self) -> Tool:
+        from neutron.ai.tools import _build_parameters_schema
+
+        async def handoff_fn(**kwargs: Any) -> str:
+            target = self.target_cls()
+            # The first arg is typically the prompt/topic
+            prompt = " ".join(str(v) for v in kwargs.values())
+            result = await target.run(prompt)
+            return cast(str, result.content)
+
+        t = Tool(handoff_fn, name=self.name)
+        t.description = self.description or f"Hand off to {self.target_cls.__name__}"
+        t.schema = _build_parameters_schema(self.fn)
+        return t
+
+
+def handoff(to: type[Any]) -> Any:
+    """Decorator to create a handoff tool to another agent.
+
+    Usage::
+
+        class TriageAgent(Agent):
+            @handoff(to=ResearchAgent)
+            async def research(self, topic: str) -> str:
+                \"\"\"Hand off to research specialist.\"\"\"
+    """
+
+    def decorator(fn: Any) -> _HandoffTool:
+        return _HandoffTool(to, fn)
+
+    return decorator

neutron/ai/mcp.py

@@ -0,0 +1,299 @@
+"""MCP (Model Context Protocol) — server and client."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Callable, cast
+
+import httpx
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from neutron.ai.tools import Tool, _build_parameters_schema
+
+
+# ---------------------------------------------------------------------------
+# MCP Server
+# ---------------------------------------------------------------------------
+
+
+class MCPServer:
+    """MCP-compatible tool + resource server.
+
+    Exposes tools and resources via a JSON-RPC-style HTTP interface
+    that can be consumed by MCP clients (Claude Desktop, other agents).
+
+    Usage::
+
+        mcp = MCPServer(name="my-tools")
+
+        @mcp.tool()
+        async def search(query: str) -> list[dict]:
+            \"\"\"Search the database.\"\"\"
+            ...
+
+        @mcp.resource("users://{user_id}")
+        async def get_user(user_id: str) -> dict:
+            \"\"\"Get user by ID.\"\"\"
+            ...
+
+        app.mount("/mcp", mcp)
+    """
+
+    def __init__(self, name: str = "neutron-mcp", version: str = "1.0.0") -> None:
+        self.name = name
+        self.version = version
+        self._tools: dict[str, Tool] = {}
+        self._resources: dict[str, _ResourceDef] = {}
+        self._asgi_app: Any = None
+
+    def tool(self, name: str | None = None) -> Callable:
+        """Decorator to register a function as an MCP tool."""
+
+        def decorator(fn: Callable) -> Callable:
+            tool_name = name or fn.__name__
+            t = Tool(fn, name=tool_name)
+            self._tools[tool_name] = t
+            return fn
+
+        return decorator
+
+    def resource(self, uri_template: str) -> Callable:
+        """Decorator to register a resource with a URI template.
+
+        URI templates use ``{param}`` placeholders::
+
+            @mcp.resource("users://{user_id}")
+            async def get_user(user_id: str) -> dict: ...
+        """
+
+        def decorator(fn: Callable) -> Callable:
+            res = _ResourceDef(uri_template, fn)
+            self._resources[uri_template] = res
+            return fn
+
+        return decorator
+
+    # --- ASGI / Starlette integration ---
+
+    async def __call__(self, scope: dict, receive: Any, send: Any) -> None:
+        """ASGI interface — route MCP requests."""
+        # The route table binds to live bound-methods of self (the handlers
+        # read self._tools / self._resources at request time), so one cached
+        # app serves every request and still sees tools/resources registered
+        # after the first request.
+        if self._asgi_app is None:
+            self._asgi_app = self._build_asgi_app()
+        await self._asgi_app(scope, receive, send)
+
+    def _build_asgi_app(self) -> Any:
+        from starlette.applications import Starlette
+        from starlette.routing import Route
+
+        routes = [
+            Route("/", self._handle_root, methods=["GET"]),
+            Route("/tools", self._handle_list_tools, methods=["GET"]),
+            Route("/tools/{tool_name}", self._handle_call_tool, methods=["POST"]),
+            Route("/resources", self._handle_list_resources, methods=["GET"]),
+            Route(
+                "/resources/{resource_path:path}",
+                self._handle_read_resource,
+                methods=["GET"],
+            ),
+        ]
+        return Starlette(routes=routes)
+
+    async def _handle_root(self, request: Request) -> JSONResponse:
+        """Server info / capabilities."""
+        return JSONResponse(
+            {
+                "name": self.name,
+                "version": self.version,
+                "protocol": "mcp",
+                "capabilities": {
+                    "tools": len(self._tools) > 0,
+                    "resources": len(self._resources) > 0,
+                },
+            }
+        )
+
+    async def _handle_list_tools(self, request: Request) -> JSONResponse:
+        """List available tools with their schemas."""
+        tools = []
+        for t in self._tools.values():
+            tools.append(
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "inputSchema": t.schema,
+                }
+            )
+        return JSONResponse({"tools": tools})
+
+    async def _handle_call_tool(self, request: Request) -> JSONResponse:
+        """Call a tool by name."""
+        tool_name = request.path_params["tool_name"]
+        tool_obj = self._tools.get(tool_name)
+        if tool_obj is None:
+            return JSONResponse(
+                {"error": f"Unknown tool: {tool_name}"}, status_code=404
+            )
+
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+
+        try:
+            result = await tool_obj(**body)
+            return JSONResponse({"result": result})
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+
+    async def _handle_list_resources(self, request: Request) -> JSONResponse:
+        """List available resources."""
+        resources = []
+        for uri_template, res in self._resources.items():
+            resources.append(
+                {
+                    "uri_template": uri_template,
+                    "name": res.fn.__name__,
+                    "description": (res.fn.__doc__ or "").strip(),
+                }
+            )
+        return JSONResponse({"resources": resources})
+
+    async def _handle_read_resource(self, request: Request) -> JSONResponse:
+        """Read a resource by URI."""
+        resource_path = request.path_params["resource_path"]
+
+        for uri_template, res in self._resources.items():
+            params = res.match(resource_path)
+            if params is not None:
+                try:
+                    result = await res.call(**params)
+                    return JSONResponse({"result": result})
+                except Exception as e:
+                    return JSONResponse({"error": str(e)}, status_code=500)
+
+        return JSONResponse(
+            {"error": f"No resource matches: {resource_path}"}, status_code=404
+        )
+
+
+# ---------------------------------------------------------------------------
+# Resource definition
+# ---------------------------------------------------------------------------
+
+
+class _ResourceDef:
+    """A resource with a URI template and handler function."""
+
+    def __init__(self, uri_template: str, fn: Callable) -> None:
+        self.uri_template = uri_template
+        self.fn = fn
+        self._is_async = _is_coroutine(fn)
+
+        # Build regex from URI template: "users://{user_id}" → "users://(?P<user_id>[^/]+)"
+        pattern = re.sub(r"\{(\w+)\}", r"(?P<\1>[^/]+)", uri_template)
+        self._pattern = re.compile(f"^{pattern}$")
+
+    def match(self, uri: str) -> dict[str, str] | None:
+        """Try to match a URI against this template. Returns params or None."""
+        m = self._pattern.match(uri)
+        if m:
+            return m.groupdict()
+        return None
+
+    async def call(self, **kwargs: Any) -> Any:
+        if self._is_async:
+            return await self.fn(**kwargs)
+        return self.fn(**kwargs)
+
+
+def _is_coroutine(fn: Callable) -> bool:
+    import inspect
+
+    return inspect.iscoroutinefunction(fn)
+
+
+# ---------------------------------------------------------------------------
+# MCP Client
+# ---------------------------------------------------------------------------
+
+
+class MCPClient:
+    """Client for connecting to MCP servers.
+
+    Usage::
+
+        async with MCPClient("http://other-service/mcp") as client:
+            tools = await client.list_tools()
+            result = await client.call_tool("search", {"query": "hello"})
+    """
+
+    def __init__(self, url: str) -> None:
+        self.url = url.rstrip("/")
+        self._client: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> MCPClient:
+        self._client = httpx.AsyncClient(timeout=60.0)
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            raise RuntimeError("MCPClient must be used as an async context manager")
+        return self._client
+
+    async def server_info(self) -> dict[str, Any]:
+        """Get server info and capabilities."""
+        client = self._ensure_client()
+        resp = await client.get(f"{self.url}/")
+        resp.raise_for_status()
+        return cast("dict[str, Any]", resp.json())
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """List available tools on the server."""
+        client = self._ensure_client()
+        resp = await client.get(f"{self.url}/tools")
+        resp.raise_for_status()
+        return cast("list[dict[str, Any]]", resp.json().get("tools", []))
+
+    async def call_tool(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> Any:
+        """Call a tool on the MCP server."""
+        client = self._ensure_client()
+        resp = await client.post(
+            f"{self.url}/tools/{name}",
+            json=arguments or {},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if "error" in data:
+            raise RuntimeError(f"MCP tool error: {data['error']}")
+        return data.get("result")
+
+    async def list_resources(self) -> list[dict[str, Any]]:
+        """List available resources on the server."""
+        client = self._ensure_client()
+        resp = await client.get(f"{self.url}/resources")
+        resp.raise_for_status()
+        return cast("list[dict[str, Any]]", resp.json().get("resources", []))
+
+    async def read_resource(self, uri: str) -> Any:
+        """Read a resource by URI."""
+        client = self._ensure_client()
+        resp = await client.get(f"{self.url}/resources/{uri}")
+        resp.raise_for_status()
+        data = resp.json()
+        if "error" in data:
+            raise RuntimeError(f"MCP resource error: {data['error']}")
+        return data.get("result")