nexus-agent-framework 0.1.0__py3-none-any.whl

nexus/__init__.py

@@ -0,0 +1,3 @@
+"""Nexus Framework: Unified application core for Google Cloud and Gemini 3.8."""
+
+__version__ = "0.1.0"

nexus/__main__.py

@@ -0,0 +1,4 @@
+from nexus.cli.main import main
+
+if __name__ == "__main__":
+    main()

nexus/agents/__init__.py

@@ -0,0 +1,6 @@
+"""Nexus Agents: Autonomous agent primitives, context, and execution runtime."""
+
+from nexus.agents.base import AgentRunResult, BaseAgent
+from nexus.agents.context import AgentContext, BudgetExceededError
+
+__all__ = ["AgentContext", "AgentRunResult", "BaseAgent", "BudgetExceededError"]

nexus/agents/base.py

@@ -0,0 +1,93 @@
+"""Nexus Agents: Base Autonomous Agent Primitive."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+from nexus.agents.context import AgentContext
+from nexus.providers.base import BaseModelProvider
+from nexus.providers.vertex import VertexAIProvider
+from nexus.security.guardrail import GuardrailManager
+from nexus.tools.base import Tool
+
+logger = logging.getLogger("nexus.agents")
+
+
+class AgentRunResult:
+    """The result of an autonomous agent task execution."""
+
+    def __init__(
+        self,
+        output: str,
+        turns: int,
+        context: AgentContext,
+    ) -> None:
+        self.output = output
+        self.turns = turns
+        self.context = context
+        self.total_cost_usd = context.accumulated_cost_usd
+        self.input_tokens = context.total_input_tokens
+        self.output_tokens = context.total_output_tokens
+
+    def __repr__(self) -> str:
+        return f"<AgentRunResult output={self.output[:40]!r}... turns={self.turns} cost=${self.total_cost_usd:.6f}>"
+
+
+class BaseAgent:
+    """
+    Autonomous AI Agent Primitive.
+    Handles reasoning, tool dispatching, security guardrails, and budget enforcement.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        system_prompt: str,
+        provider: BaseModelProvider | None = None,
+        tools: Sequence[Tool] | None = None,
+        guardrail: GuardrailManager | None = None,
+        max_budget_usd: float = 0.50,
+        max_turns: int = 6,
+    ) -> None:
+        self.name = name
+        self.system_prompt = system_prompt
+        self.provider = provider or VertexAIProvider()
+        self.tools = {t.name: t for t in (tools or [])}
+        self.guardrail = guardrail or GuardrailManager()
+        self.max_budget_usd = max_budget_usd
+        self.max_turns = max_turns
+
+    def run(self, task: str) -> AgentRunResult:
+        """Execute a task autonomously."""
+        # 1. Inspect and scrub input via security guardrails
+        clean_task = self.guardrail.inspect_input(task)
+
+        # 2. Initialize execution context with spend limit
+        context = AgentContext(max_budget_usd=self.max_budget_usd)
+        context.add_user_message(clean_task)
+
+        tool_schemas = [t.schema for t in self.tools.values()]
+        turn_count = 0
+
+        for turn in range(self.max_turns):
+            turn_count += 1
+            # Execute model turn
+            resp = self.provider.converse(
+                messages=context.messages,
+                tools=tool_schemas,
+                system_instruction=self.system_prompt,
+            )
+            context.record_usage(resp.input_tokens, resp.output_tokens, resp.cost_usd)
+
+            # Check if tools were executed or final answer returned
+            # If plain text returned
+            if resp.text:
+                context.add_model_message(resp.text)
+                return AgentRunResult(output=resp.text, turns=turn_count, context=context)
+
+        return AgentRunResult(
+            output="Agent completed max turns without final message.",
+            turns=turn_count,
+            context=context,
+        )

nexus/agents/context.py

@@ -0,0 +1,45 @@
+"""Nexus Agents: Execution Context, memory, and budget tracking."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+
+class BudgetExceededError(Exception):
+    """Raised when an agent session hits its spend ceiling."""
+
+
+class AgentContext:
+    """Manages working memory, message logs, and spend ledger for an agent run."""
+
+    def __init__(
+        self,
+        session_id: str | None = None,
+        max_budget_usd: float = 0.50,  # Default safety cap: $0.50 max per run
+    ) -> None:
+        self.session_id = session_id or str(uuid.uuid4())
+        self.max_budget_usd = max_budget_usd
+        self.messages: list[dict[str, Any]] = []
+        self.tool_executions: list[dict[str, Any]] = []
+        self.accumulated_cost_usd: float = 0.0
+        self.total_input_tokens: int = 0
+        self.total_output_tokens: int = 0
+
+    def record_usage(self, input_tokens: int, output_tokens: int, cost_usd: float) -> None:
+        """Record model inference tokens and check budget ceiling."""
+        self.total_input_tokens += input_tokens
+        self.total_output_tokens += output_tokens
+        self.accumulated_cost_usd += cost_usd
+
+        if self.accumulated_cost_usd > self.max_budget_usd:
+            raise BudgetExceededError(
+                f"Agent session {self.session_id} exceeded max budget of ${self.max_budget_usd:.4f} "
+                f"(current cost: ${self.accumulated_cost_usd:.4f})"
+            )
+
+    def add_user_message(self, text: str) -> None:
+        self.messages.append({"role": "user", "parts": [{"text": text}]})
+
+    def add_model_message(self, text: str) -> None:
+        self.messages.append({"role": "model", "parts": [{"text": text}]})

nexus/ai/__init__.py

@@ -0,0 +1,18 @@
+"""Nexus AI package: Vertex AI & Gemini 3.8 client, pricing, and structured output."""
+
+from nexus.ai.client import (
+    GeminiClient,
+    GeminiResponse,
+    get_gcp_access_token,
+    get_gcp_project,
+)
+from nexus.ai.pricing import DEFAULT_MODEL, calculate_cost_usd
+
+__all__ = [
+    "DEFAULT_MODEL",
+    "GeminiClient",
+    "GeminiResponse",
+    "calculate_cost_usd",
+    "get_gcp_access_token",
+    "get_gcp_project",
+]

nexus/ai/client.py

@@ -0,0 +1,390 @@
+"""Nexus AI: Standardized Google Cloud Vertex AI & Gemini 3.8 Client."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+import time
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from nexus.ai.pricing import DEFAULT_MODEL, calculate_cost_usd
+
+logger = logging.getLogger("nexus.ai")
+
+# Cache token locally for 40 minutes to prevent overhead
+_CACHED_TOKEN: tuple[str, float] | None = None
+_TOKEN_TTL_SECONDS = 40 * 60
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def get_gcp_project() -> str:
+    """Resolve the active Google Cloud project ID."""
+    proj = os.getenv("GCP_PROJECT_ID") or os.getenv("GOOGLE_CLOUD_PROJECT")
+    if proj:
+        return proj
+    gcloud_bin = shutil.which("gcloud") or shutil.which("gcloud.cmd")
+    if gcloud_bin:
+        try:
+            res = subprocess.run(
+                [gcloud_bin, "config", "get-value", "project"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+            val = res.stdout.strip()
+            if val and val != "(unset)":
+                return val
+        except Exception:
+            pass
+    return "finhub-510316"
+
+
+def get_gcp_access_token() -> str | None:
+    """Acquire an OAuth access token via IAM instance metadata or gcloud CLI."""
+    global _CACHED_TOKEN
+    now = time.time()
+    if _CACHED_TOKEN and (now - _CACHED_TOKEN[1]) < _TOKEN_TTL_SECONDS:
+        return _CACHED_TOKEN[0]
+
+    # 1. Environment token override
+    env_token = os.getenv("GCP_ACCESS_TOKEN") or os.getenv("GOOGLE_OAUTH_ACCESS_TOKEN")
+    if env_token:
+        _CACHED_TOKEN = (env_token.strip(), now)
+        return env_token.strip()
+
+    # 2. Check GCP Compute Engine / Cloud Run instance metadata server
+    try:
+        resp = httpx.get(
+            "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token",
+            headers={"Metadata-Flavor": "Google"},
+            timeout=1.5,
+        )
+        if resp.status_code == 200:
+            token = resp.json().get("access_token")
+            if token:
+                _CACHED_TOKEN = (token, now)
+                return str(token)
+    except Exception:
+        pass
+
+    # 3. Local development fallback: gcloud auth print-access-token
+    gcloud_bin = shutil.which("gcloud") or shutil.which("gcloud.cmd")
+    if gcloud_bin:
+        try:
+            res = subprocess.run(
+                [gcloud_bin, "auth", "print-access-token"],
+                capture_output=True,
+                text=True,
+                timeout=15,
+                check=False,
+            )
+            token = res.stdout.strip()
+            if token and res.returncode == 0 and not token.startswith("ERROR"):
+                _CACHED_TOKEN = (token, now)
+                return token
+        except Exception as exc:
+            logger.debug("Local gcloud token lookup failed: %s", exc)
+
+    return None
+
+
+class GeminiResponse:
+    """Normalized response from Gemini 3.8."""
+
+    def __init__(
+        self,
+        text: str,
+        input_tokens: int,
+        output_tokens: int,
+        cost_usd: float,
+        model: str,
+        raw: Mapping[str, Any],
+    ) -> None:
+        self.text = text
+        self.input_tokens = input_tokens
+        self.output_tokens = output_tokens
+        self.cost_usd = cost_usd
+        self.model = model
+        self.raw = raw
+
+    def __repr__(self) -> str:
+        return f"<GeminiResponse model={self.model} cost=${self.cost_usd:.6f} length={len(self.text)}>"
+
+
+class GeminiClient:
+    """
+    Standardized client for Google Cloud Vertex AI & Gemini 3.8 Flash.
+    Provides structured schema extraction, multimodal parsing, and multi-turn tool loops.
+    """
+
+    def __init__(
+        self,
+        project_id: str | None = None,
+        location: str = "global",
+        api_key: str | None = None,
+        default_model: str = DEFAULT_MODEL,
+    ) -> None:
+        self.project_id = project_id or get_gcp_project()
+        self.location = location
+        self.api_key = api_key or os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+        self.default_model = default_model
+        self._http = httpx.Client(timeout=httpx.Timeout(180.0, connect=30.0, read=180.0))
+
+    def _post(
+        self,
+        url: str,
+        headers: dict[str, str],
+        body: dict[str, Any],
+        max_retries: int = 2,
+    ) -> httpx.Response:
+        import time
+
+        for attempt in range(max_retries):
+            try:
+                return self._http.post(url, headers=headers, json=body)
+            except (httpx.ReadTimeout, httpx.ConnectTimeout):
+                if attempt == max_retries - 1:
+                    raise
+                time.sleep(2.0)
+        raise RuntimeError("HTTP request failed after max retries")
+
+    def _build_url_and_headers(self, model: str) -> tuple[str, dict[str, str]]:
+        token = get_gcp_access_token()
+        if token:
+            # Vertex AI global or regional publisher endpoint
+            if self.location == "global":
+                url = (
+                    f"https://aiplatform.googleapis.com/v1/projects/{self.project_id}"
+                    f"/locations/global/publishers/google/models/{model}:generateContent"
+                )
+            else:
+                url = (
+                    f"https://{self.location}-aiplatform.googleapis.com/v1/projects/{self.project_id}"
+                    f"/locations/{self.location}/publishers/google/models/{model}:generateContent"
+                )
+            headers = {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            }
+            return url, headers
+
+        if self.api_key:
+            # Direct Google Generative Language API
+            url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={self.api_key}"
+            headers = {"Content-Type": "application/json"}
+            return url, headers
+
+        raise RuntimeError(
+            "No Google Cloud authentication found. Provide GCP IAM credentials, run "
+            "'gcloud auth application-default login', or set GEMINI_API_KEY."
+        )
+
+    def generate(
+        self,
+        prompt: str,
+        system_instruction: str | None = None,
+        model: str | None = None,
+        temperature: float = 0.2,
+    ) -> GeminiResponse:
+        """Execute a text completion turn."""
+        chosen_model = model or self.default_model
+        url, headers = self._build_url_and_headers(chosen_model)
+
+        body: dict[str, Any] = {
+            "contents": [{"role": "user", "parts": [{"text": prompt}]}],
+            "generationConfig": {
+                "temperature": temperature,
+                "thinkingConfig": {"thinkingLevel": "low"},
+            },
+        }
+        if system_instruction:
+            body["systemInstruction"] = {"parts": [{"text": system_instruction}]}
+
+        resp = self._post(url, headers=headers, body=body)
+        if resp.status_code != 200:
+            raise RuntimeError(f"Gemini API returned status {resp.status_code}: {resp.text}")
+
+        data = resp.json()
+        usage = data.get("usageMetadata", {})
+        inp = int(usage.get("promptTokenCount", 0))
+        out = int(usage.get("candidatesTokenCount", 0))
+        cost = calculate_cost_usd(inp, out, chosen_model)
+
+        candidates = data.get("candidates", [])
+        text = ""
+        if candidates:
+            parts = candidates[0].get("content", {}).get("parts", [])
+            for p in parts:
+                if "text" in p:
+                    text += p["text"]
+
+        return GeminiResponse(
+            text=text.strip(),
+            input_tokens=inp,
+            output_tokens=out,
+            cost_usd=cost,
+            model=chosen_model,
+            raw=data,
+        )
+
+    def structured(
+        self,
+        prompt: str,
+        response_model: type[T],
+        system_instruction: str | None = None,
+        inline_pdf_bytes: bytes | None = None,
+        model: str | None = None,
+    ) -> T:
+        """Extract a strongly typed Pydantic schema using constrained JSON generation."""
+        chosen_model = model or self.default_model
+        url, headers = self._build_url_and_headers(chosen_model)
+
+        parts: list[dict[str, Any]] = []
+        if inline_pdf_bytes:
+            import base64
+
+            b64 = base64.b64encode(inline_pdf_bytes).decode("ascii")
+            parts.append({"inlineData": {"mimeType": "application/pdf", "data": b64}})
+        parts.append({"text": prompt})
+
+        # Generate JSON Schema from Pydantic model
+        schema = response_model.model_json_schema()
+        # Clean $defs / titles if needed for Gemini schema compatibility
+        clean_schema = self._sanitize_schema(schema)
+
+        body: dict[str, Any] = {
+            "contents": [{"role": "user", "parts": parts}],
+            "generationConfig": {
+                "temperature": 0.0,
+                "responseMimeType": "application/json",
+                "responseSchema": clean_schema,
+                "thinkingConfig": {"thinkingLevel": "low"},
+            },
+        }
+        if system_instruction:
+            body["systemInstruction"] = {"parts": [{"text": system_instruction}]}
+
+        resp = self._post(url, headers=headers, body=body)
+        if resp.status_code != 200:
+            raise RuntimeError(f"Gemini structured output failed {resp.status_code}: {resp.text}")
+
+        data = resp.json()
+        candidates = data.get("candidates", [])
+        if not candidates:
+            raise RuntimeError(f"No candidates returned in structured output: {data}")
+
+        parts_out = candidates[0].get("content", {}).get("parts", [])
+        raw_text = "".join(p.get("text", "") for p in parts_out).strip()
+        parsed_json = json.loads(raw_text)
+        return response_model.model_validate(parsed_json)
+
+    def converse(
+        self,
+        messages: Sequence[dict[str, Any]],
+        tools: Sequence[Callable[..., Any]] | Sequence[dict[str, Any]],
+        system_instruction: str | None = None,
+        max_turns: int = 5,
+        model: str | None = None,
+    ) -> GeminiResponse:
+        """Multi-turn tool-calling loop executing tools locally without hallucinations."""
+        chosen_model = model or self.default_model
+        url, headers = self._build_url_and_headers(chosen_model)
+
+        # Convert tools to function declarations
+        func_declarations: list[dict[str, Any]] = []
+        tool_dispatch: dict[str, Callable[..., Any]] = {}
+        for t in tools:
+            if callable(t):
+                fn_name = getattr(t, "__name__", "tool")
+                doc = getattr(t, "__doc__", "") or f"Execute {fn_name}"
+                tool_dispatch[fn_name] = t
+                func_declarations.append(
+                    {
+                        "name": fn_name,
+                        "description": doc.strip(),
+                        "parameters": {"type": "object", "properties": {}},
+                    }
+                )
+            elif isinstance(t, dict):
+                func_declarations.append(t)
+
+        current_contents = list(messages)
+        total_inp = 0
+        total_out = 0
+
+        for _ in range(max_turns):
+            body: dict[str, Any] = {
+                "contents": current_contents,
+                "generationConfig": {
+                    "temperature": 0.1,
+                    "thinkingConfig": {"thinkingLevel": "low"},
+                },
+            }
+            if func_declarations:
+                body["tools"] = [{"functionDeclarations": func_declarations}]
+            if system_instruction:
+                body["systemInstruction"] = {"parts": [{"text": system_instruction}]}
+
+            resp = self._post(url, headers=headers, body=body)
+            if resp.status_code != 200:
+                raise RuntimeError(f"Gemini converse error {resp.status_code}: {resp.text}")
+
+            data = resp.json()
+            usage = data.get("usageMetadata", {})
+            total_inp += int(usage.get("promptTokenCount", 0))
+            total_out += int(usage.get("candidatesTokenCount", 0))
+
+            candidate = (data.get("candidates") or [{}])[0]
+            content = candidate.get("content", {})
+            parts = content.get("parts", [])
+
+            # Check if model requested tool call
+            function_calls = [p["functionCall"] for p in parts if "functionCall" in p]
+            if not function_calls:
+                # Text answer completed
+                text = "".join(p.get("text", "") for p in parts).strip()
+                cost = calculate_cost_usd(total_inp, total_out, chosen_model)
+                return GeminiResponse(text, total_inp, total_out, cost, chosen_model, data)
+
+            # Append model turn to conversation
+            current_contents.append({"role": "model", "parts": parts})
+
+            # Execute tool and append functionResponse
+            response_parts = []
+            for call in function_calls:
+                name = call.get("name", "")
+                args = call.get("args", {})
+                fn = tool_dispatch.get(name)
+                try:
+                    result = fn(**args) if fn else {"status": "error", "message": f"Tool {name} not found"}
+                except Exception as exc:
+                    result = {"status": "error", "message": str(exc)}
+
+                response_parts.append(
+                    {
+                        "functionResponse": {
+                            "name": name,
+                            "response": {"output": result if isinstance(result, (dict, list)) else str(result)},
+                        }
+                    }
+                )
+            current_contents.append({"role": "user", "parts": response_parts})
+
+        raise RuntimeError(f"Gemini converse exceeded max_turns={max_turns}")
+
+    @staticmethod
+    def _sanitize_schema(schema: dict[str, Any]) -> dict[str, Any]:
+        """Strip keywords unsupported by Gemini JSON Schema parser."""
+        s: dict[str, Any] = dict(json.loads(json.dumps(schema)))
+        for key in ("title", "$defs", "$schema", "default"):
+            s.pop(key, None)
+        return s

nexus/ai/pricing.py

@@ -0,0 +1,28 @@
+"""Token pricing and spend tracking for Vertex AI models."""
+
+from __future__ import annotations
+
+from typing import Final
+
+# Vertex AI Gemini 3.8 Flash pricing per million tokens
+GEMINI_3_8_FLASH_INPUT_PER_M: Final[float] = 0.075
+GEMINI_3_8_FLASH_OUTPUT_PER_M: Final[float] = 0.30
+
+# Fallback default model
+DEFAULT_MODEL: Final[str] = "gemini-3.8-flash"
+
+
+def calculate_cost_usd(
+    input_tokens: int,
+    output_tokens: int,
+    model: str = DEFAULT_MODEL,
+) -> float:
+    """Calculate the estimated USD cost for a model call."""
+    if "gemini-3.8" in model or "gemini-3" in model:
+        in_cost = (input_tokens / 1_000_000.0) * GEMINI_3_8_FLASH_INPUT_PER_M
+        out_cost = (output_tokens / 1_000_000.0) * GEMINI_3_8_FLASH_OUTPUT_PER_M
+        return in_cost + out_cost
+    # Standard Gemini 2.x / 1.5 pricing baseline
+    in_cost = (input_tokens / 1_000_000.0) * 0.15
+    out_cost = (output_tokens / 1_000_000.0) * 0.60
+    return in_cost + out_cost

nexus/api/__init__.py

@@ -0,0 +1,14 @@
+"""Nexus API package: Application factory and middleware."""
+
+from nexus.ai.client import GeminiClient
+from nexus.api.app import create_nexus_app
+from nexus.api.middleware import NexusTelemetryMiddleware
+from nexus.db.base import Base, NexusEntity
+
+__all__ = [
+    "Base",
+    "GeminiClient",
+    "NexusEntity",
+    "NexusTelemetryMiddleware",
+    "create_nexus_app",
+]