internet2agent 0.1.0__py3-none-any.whl

internet2agent/__init__.py

@@ -0,0 +1,17 @@
+"""Python interface and Claude-powered agent for the Internet2 Periscope
+Looking Glass MCP server (https://periscope.ns.internet2.edu/mcp)."""
+
+from .agent import Internet2Agent
+from .config import Settings
+from .periscope import AsyncPeriscopeClient, PeriscopeClient, PeriscopeError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncPeriscopeClient",
+    "Internet2Agent",
+    "PeriscopeClient",
+    "PeriscopeError",
+    "Settings",
+    "__version__",
+]

internet2agent/agent.py

@@ -0,0 +1,207 @@
+"""Natural-language agent for the Internet2 Periscope service.
+
+Works with any OpenAI-compatible chat-completions endpoint (OpenAI, Ollama,
+vLLM, LM Studio, OpenRouter, ...). The agent fetches the Looking Glass tool
+schemas from the Periscope MCP server, exposes them to the model as function
+tools, executes the model's tool calls through :class:`PeriscopeClient`, and
+loops until the model produces a final answer.
+
+Configuration (``.env`` / environment):
+
+- ``OPENAI_BASE_URL`` - endpoint base URL (unset = api.openai.com)
+- ``OPENAI_API_KEY``  - API key (optional for local endpoints)
+- ``I2A_MODEL``       - model name to request
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+from openai import OpenAI
+
+from .config import Settings
+from .periscope import PeriscopeClient, PeriscopeError
+
+SYSTEM_PROMPT = """\
+You are a network operations assistant for the Internet2 research & education
+backbone. You answer questions by running diagnostics through Periscope, the
+Internet2 Looking Glass MCP service, using the tools provided.
+
+Workflow for every diagnostic question:
+1. Call lg_devices to discover device IDs and platforms. Device IDs passed to
+   lg_execute must exactly match the `name` field from lg_devices.
+2. Call lg_commands to confirm the command is supported on the target
+   platforms; call lg_filters if you want to narrow the output.
+3. Call lg_execute with at most 10 targets. Commands must match documented
+   syntax exactly - no abbreviations. When targeting mixed platforms, the
+   command and filter must be supported on every target platform.
+
+Report findings concisely. Quote the raw output lines that support your
+conclusion and name the device each line came from. If a command fails or a
+device is unknown, say so plainly and suggest the closest valid option.
+"""
+
+_MAX_STEPS = 25
+_MAX_RESULT_CHARS = 60_000  # keep one giant router dump from blowing the context window
+
+
+class Internet2Agent:
+    """Multi-turn natural-language interface to Periscope.
+
+    >>> with Internet2Agent() as agent:
+    ...     print(agent.ask("Which devices are in Chicago?"))
+
+    History is kept on the instance so follow-up questions work; call
+    :meth:`reset` to start fresh. Use as a context manager (or call
+    :meth:`close`) to release the underlying MCP session.
+    """
+
+    def __init__(
+        self,
+        settings: Settings | None = None,
+        client: OpenAI | None = None,
+        periscope: PeriscopeClient | None = None,
+        model: str | None = None,
+        max_steps: int = _MAX_STEPS,
+        max_result_chars: int = _MAX_RESULT_CHARS,
+    ) -> None:
+        self.settings = settings or Settings.from_env()
+        if client is None:
+            client = OpenAI(
+                base_url=self.settings.openai_base_url,
+                # Local OpenAI-compatible servers usually ignore the key, but
+                # the SDK requires one - send a placeholder when unset.
+                api_key=self.settings.openai_api_key or "not-needed",
+            )
+        self.client = client
+        self.model = model or self.settings.model
+        self.max_steps = max_steps
+        self.max_result_chars = max_result_chars
+        self.periscope = periscope or PeriscopeClient(settings=self.settings)
+        self.messages: list[dict[str, Any]] = [{"role": "system", "content": SYSTEM_PROMPT}]
+        self._tools: list[dict[str, Any]] | None = None
+
+    # -- lifecycle ------------------------------------------------------------
+
+    def close(self) -> None:
+        self.periscope.close()
+
+    def __enter__(self) -> "Internet2Agent":
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()
+
+    # -- tool plumbing --------------------------------------------------------
+
+    def _openai_tools(self) -> list[dict[str, Any]]:
+        """Looking Glass tools converted to OpenAI function-tool schemas."""
+        if self._tools is None:
+            self._tools = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": tool["name"],
+                        "description": tool.get("description") or "",
+                        "parameters": tool.get("input_schema")
+                        or {"type": "object", "properties": {}},
+                    },
+                }
+                for tool in self.periscope.tools()
+            ]
+        return self._tools
+
+    def _run_tool_call(self, name: Any, raw_arguments: str) -> str:
+        if not isinstance(name, str) or not name:
+            return "ERROR: tool call is missing a valid tool name"
+        try:
+            arguments = json.loads(raw_arguments) if raw_arguments else {}
+        except ValueError:
+            return f"ERROR: tool arguments were not valid JSON: {raw_arguments!r}"
+        if not isinstance(arguments, dict):
+            return f"ERROR: tool arguments must be a JSON object, got: {raw_arguments!r}"
+        try:
+            result = self.periscope.call(name, arguments)
+        except (PeriscopeError, TimeoutError) as exc:
+            return f"ERROR: {exc}"
+        except Exception as exc:  # transport/protocol failures - let the model adapt
+            return f"ERROR: {type(exc).__name__}: {exc}"
+        content = result if isinstance(result, str) else json.dumps(result, default=str)
+        if len(content) > self.max_result_chars:
+            dropped = len(content) - self.max_result_chars
+            content = content[: self.max_result_chars] + f"\n...[truncated {dropped} characters]"
+        return content
+
+    # -- conversation ---------------------------------------------------------
+
+    def ask(
+        self,
+        question: str,
+        on_tool: Callable[[str, str], None] | None = None,
+    ) -> str:
+        """Ask a question and return the assistant's final text.
+
+        ``on_tool`` (if given) is called with ``(tool_name, raw_arguments)``
+        before each tool execution - useful for progress display.
+        """
+        self.messages.append({"role": "user", "content": question})
+        for _ in range(self.max_steps):
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=self.messages,
+                tools=self._openai_tools(),
+            )
+            message = response.choices[0].message
+
+            # Normalize tool calls defensively: lenient OpenAI-compatible servers
+            # can yield a missing name or dict-typed arguments.
+            tool_calls = []
+            for call in message.tool_calls or []:
+                function = getattr(call, "function", None)
+                raw = getattr(function, "arguments", None)
+                if isinstance(raw, dict):
+                    raw = json.dumps(raw)
+                elif not isinstance(raw, str):
+                    raw = ""
+                tool_calls.append(
+                    {
+                        "id": getattr(call, "id", None) or "",
+                        "name": getattr(function, "name", None),
+                        "arguments": raw,
+                    }
+                )
+
+            assistant_msg: dict[str, Any] = {"role": "assistant", "content": message.content}
+            if tool_calls:
+                assistant_msg["tool_calls"] = [
+                    {
+                        "id": call["id"],
+                        "type": "function",
+                        "function": {
+                            "name": call["name"] or "",
+                            "arguments": call["arguments"],
+                        },
+                    }
+                    for call in tool_calls
+                ]
+            self.messages.append(assistant_msg)
+
+            if not tool_calls:
+                return message.content or ""
+
+            for call in tool_calls:
+                if on_tool is not None:
+                    on_tool(call["name"] or "?", call["arguments"])
+                self.messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": call["id"],
+                        "content": self._run_tool_call(call["name"], call["arguments"]),
+                    }
+                )
+        return "[stopped: the model kept calling tools past the step limit]"
+
+    def reset(self) -> None:
+        """Clear the conversation history (keeps the system prompt)."""
+        del self.messages[1:]

internet2agent/cli.py

@@ -0,0 +1,291 @@
+"""Command-line interface for internet2agent.
+
+Direct Looking Glass access (no credentials needed):
+
+    internet2agent info
+    internet2agent devices
+    internet2agent commands
+    internet2agent filters
+    internet2agent exec "show bgp" -t rtr1 rtr2 -p summary -f "include Established"
+
+Natural-language agent (configure your OpenAI-compatible endpoint in .env):
+
+    internet2agent ask "Is BGP healthy between Chicago and Seattle?"
+    internet2agent chat
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import sys
+from typing import Any
+
+import openai
+
+from .agent import Internet2Agent
+from .config import DEFAULT_MODEL, Settings, save_env_values
+from .periscope import PeriscopeClient, PeriscopeError
+
+_DEVICE_COLUMNS = ["name", "location", "type", "platform"]
+_COMMAND_COLUMNS = ["name", "platforms", "help"]
+
+
+def _print_json(data: Any) -> None:
+    print(json.dumps(data, indent=2))
+
+
+def _print_table(rows: list[dict[str, Any]], preferred: list[str]) -> None:
+    if not rows:
+        print("(no results)")
+        return
+    seen: dict[str, None] = {}
+    for row in rows:
+        for key in row:
+            seen[key] = None
+    columns = [c for c in preferred if c in seen] + [c for c in seen if c not in preferred]
+
+    def cell(row: dict[str, Any], col: str) -> str:
+        value = row.get(col, "")
+        if isinstance(value, (list, tuple)):
+            return ", ".join(str(v) for v in value)
+        return "" if value is None else str(value)
+
+    widths = {c: max(len(c), *(len(cell(r, c)) for r in rows)) for c in columns}
+    print("  ".join(c.upper().ljust(widths[c]) for c in columns))
+    print("  ".join("-" * widths[c] for c in columns))
+    for row in rows:
+        print("  ".join(cell(row, c).ljust(widths[c]) for c in columns))
+
+
+def _rows(data: Any, *keys: str) -> list[dict[str, Any]] | None:
+    """Coerce a tool result into a list of dicts, unwrapping one level if needed."""
+    if isinstance(data, dict):
+        for key in keys:
+            if isinstance(data.get(key), list):
+                data = data[key]
+                break
+    if isinstance(data, list) and all(isinstance(item, dict) for item in data):
+        return data
+    return None
+
+
+def _show(data: Any, as_json: bool, preferred: list[str], *unwrap_keys: str) -> None:
+    rows = None if as_json else _rows(data, *unwrap_keys)
+    if rows is None:
+        _print_json(data)
+    else:
+        _print_table(rows, preferred)
+
+
+def _cmd_info(args: argparse.Namespace) -> None:
+    with PeriscopeClient() as lg:
+        _print_json(lg.config())
+
+
+def _cmd_devices(args: argparse.Namespace) -> None:
+    with PeriscopeClient() as lg:
+        _show(lg.devices(), args.json, _DEVICE_COLUMNS, "devices")
+
+
+def _cmd_commands(args: argparse.Namespace) -> None:
+    with PeriscopeClient() as lg:
+        _show(lg.commands(), args.json, _COMMAND_COLUMNS, "commands")
+
+
+def _cmd_filters(args: argparse.Namespace) -> None:
+    with PeriscopeClient() as lg:
+        _show(lg.filters(), args.json, ["name", "platforms", "help"], "filters")
+
+
+def _cmd_exec(args: argparse.Namespace) -> None:
+    with PeriscopeClient() as lg:
+        result = lg.execute(
+            args.command,
+            args.targets,
+            parameter=args.parameter,
+            filter=args.filter,
+        )
+    if args.json or not isinstance(result, dict) or "outputs" not in result:
+        _print_json(result)
+        return
+    for output in result["outputs"]:
+        if isinstance(output, dict):
+            target = output.get("target") or output.get("device") or "?"
+            body = output.get("output")
+            if not isinstance(body, str):
+                body = json.dumps(output, indent=2)
+            status = output.get("status")
+        else:
+            target, body, status = "?", str(output), None
+        suffix = f"  [status: {status}]" if status not in (None, "ok") else ""
+        print(f"=== {target}{suffix} ===")
+        print(body.rstrip("\n"))
+        print()
+
+
+def _show_tool_call(name: str, raw_arguments: str) -> None:
+    print(f"  [{name} {raw_arguments}]", flush=True)
+
+
+def _onboard_llm() -> Settings:
+    """First-run setup: collect the OpenAI-compatible endpoint interactively."""
+    print("No LLM endpoint is configured yet (OPENAI_BASE_URL / OPENAI_API_KEY are both unset).")
+    print("The agent works with any OpenAI-compatible endpoint, for example:")
+    print("  OpenAI:    leave the base URL blank and paste an API key")
+    print("  Ollama:    http://localhost:11434/v1   (no key needed)")
+    print("  LM Studio: http://localhost:1234/v1    (no key needed)")
+    if not sys.stdin.isatty():
+        print(
+            "error: non-interactive session - set OPENAI_BASE_URL / OPENAI_API_KEY / "
+            "I2A_MODEL in .env or the environment.",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    print()
+    base_url = input("LLM base URL [blank = api.openai.com]: ").strip()
+    api_key = getpass.getpass("API key (hidden) [blank if the endpoint needs none]: ").strip()
+    if not base_url and not api_key:
+        print("error: nothing entered - the agent needs at least a base URL or an API key.",
+              file=sys.stderr)
+        raise SystemExit(2)
+    model = input(f"Model name [{DEFAULT_MODEL}]: ").strip() or DEFAULT_MODEL
+
+    values = {"I2A_MODEL": model}
+    if base_url:
+        values["OPENAI_BASE_URL"] = base_url
+    if api_key:
+        values["OPENAI_API_KEY"] = api_key
+    os.environ.update(values)  # takes effect for this run
+
+    save = input("Save to .env for future runs? [Y/n]: ").strip().lower()
+    if save in ("", "y", "yes"):
+        print(f"(saved to {save_env_values(values)})")
+    print()
+    return Settings.from_env()
+
+
+def _make_agent() -> Internet2Agent:
+    settings = Settings.from_env()
+    if not (settings.openai_api_key or settings.openai_base_url):
+        settings = _onboard_llm()
+    return Internet2Agent(settings=settings)
+
+
+def _cmd_ask(args: argparse.Namespace) -> None:
+    with _make_agent() as agent:
+        print(agent.ask(" ".join(args.question), on_tool=_show_tool_call))
+
+
+def _cmd_chat(args: argparse.Namespace) -> None:
+    with _make_agent() as agent:
+        print("Internet2 Periscope agent. Type 'exit' to quit, 'reset' to clear history.")
+        while True:
+            try:
+                line = input("you> ").strip()
+            except (EOFError, KeyboardInterrupt):
+                print()
+                return
+            if not line:
+                continue
+            if line.lower() in {"exit", "quit"}:
+                return
+            if line.lower() == "reset":
+                agent.reset()
+                print("(history cleared)")
+                continue
+            try:
+                reply = agent.ask(line, on_tool=_show_tool_call)
+            except KeyboardInterrupt:
+                print("\n(interrupted - session kept, ask again or 'exit')")
+                continue
+            print(f"agent> {reply}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="internet2agent",
+        description="Internet2 Periscope Looking Glass - direct client and Claude agent",
+    )
+    sub = parser.add_subparsers(dest="subcommand", required=True)
+
+    def lg_sub(name: str, help_text: str, func: Any) -> argparse.ArgumentParser:
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("--json", action="store_true", help="print raw JSON")
+        p.set_defaults(func=func)
+        return p
+
+    lg_sub("info", "show service limits (rate limit, max targets)", _cmd_info)
+    lg_sub("devices", "list available devices", _cmd_devices)
+    lg_sub("commands", "list supported commands", _cmd_commands)
+    lg_sub("filters", "list output filters", _cmd_filters)
+
+    p_exec = lg_sub("exec", "run a command on one or more devices", _cmd_exec)
+    p_exec.add_argument("command", help='command name, e.g. "show bgp" or "traceroute"')
+    p_exec.add_argument(
+        "-t", "--targets", nargs="+", required=True, metavar="DEVICE",
+        help="device IDs from 'devices' (max 10)",
+    )
+    p_exec.add_argument("-p", "--parameter", help='appended argument, e.g. "10.0.0.0/8" or "summary"')
+    p_exec.add_argument("-f", "--filter", help='output filter, e.g. "include bgp" or "exclude ^$"')
+
+    p_ask = sub.add_parser("ask", help="ask the LLM agent one question (configure LLM in .env)")
+    p_ask.add_argument("question", nargs="+", help="the question to ask")
+    p_ask.set_defaults(func=_cmd_ask)
+
+    p_chat = sub.add_parser("chat", help="interactive agent session (configure LLM in .env)")
+    p_chat.set_defaults(func=_cmd_chat)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        args.func(args)
+    except PeriscopeError as exc:
+        print(f"periscope error: {exc}", file=sys.stderr)
+        return 1
+    except openai.AuthenticationError:
+        print(
+            "error: the LLM endpoint rejected the API key.\n"
+            "Set OPENAI_API_KEY (and OPENAI_BASE_URL if not using OpenAI) in .env.",
+            file=sys.stderr,
+        )
+        return 2
+    except openai.NotFoundError as exc:
+        print(
+            f"error: the LLM endpoint returned 404: {exc}\n"
+            "Check I2A_MODEL (and OPENAI_BASE_URL) in .env - the endpoint may not serve that model.",
+            file=sys.stderr,
+        )
+        return 2
+    except openai.RateLimitError:
+        print("error: LLM endpoint rate limit hit - try again shortly.", file=sys.stderr)
+        return 2
+    except openai.APIStatusError as exc:
+        print(f"error: LLM endpoint returned {exc.status_code}: {exc.message}", file=sys.stderr)
+        return 2
+    except openai.APIConnectionError:
+        print(
+            "error: could not reach the LLM endpoint - check OPENAI_BASE_URL in .env "
+            "and that the server is running.",
+            file=sys.stderr,
+        )
+        return 2
+    except openai.OpenAIError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except TimeoutError:
+        print("error: Periscope MCP call timed out.", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print(file=sys.stderr)
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

internet2agent/config.py

@@ -0,0 +1,86 @@
+"""Environment-driven configuration for internet2agent.
+
+Credentials and settings come from environment variables, optionally loaded
+from a ``.env`` file (current directory first, then the project root):
+
+- ``OPENAI_BASE_URL``      - OpenAI-compatible endpoint for the agent's LLM
+                             (unset = api.openai.com; e.g. Ollama:
+                             ``http://localhost:11434/v1``).
+- ``OPENAI_API_KEY``       - API key for that endpoint (optional for local
+                             endpoints that don't check keys).
+- ``I2A_MODEL``            - model name the agent requests (default: gpt-4o;
+                             set it to whatever your endpoint serves).
+- ``PERISCOPE_MCP_URL``    - Periscope MCP endpoint (default below).
+- ``PERISCOPE_AUTH_TOKEN`` - future Internet2/Periscope bearer token. The
+                             server currently requires no credentials; leave
+                             unset until Internet2 issues one.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+DEFAULT_MCP_URL = "https://periscope.ns.internet2.edu/mcp"
+DEFAULT_MODEL = "gpt-4o"
+
+_PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+
+def load_env() -> None:
+    """Load ``.env`` from the current directory, then the project root.
+
+    Real environment variables always win; among ``.env`` files, the first one
+    that defines a key wins.
+    """
+    load_dotenv()
+    load_dotenv(_PROJECT_ROOT / ".env")
+
+
+def _clean(value: str | None) -> str | None:
+    value = (value or "").strip()
+    return value or None
+
+
+def env_file_path() -> Path:
+    """The project-root .env file (may not exist yet)."""
+    return _PROJECT_ROOT / ".env"
+
+
+def save_env_values(values: dict[str, str], path: Path | None = None) -> Path:
+    """Write ``KEY=value`` pairs into ``.env``, updating lines that already set them."""
+    path = path or env_file_path()
+    lines = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    remaining = dict(values)
+    for index, line in enumerate(lines):
+        stripped = line.strip()
+        for key in list(remaining):
+            if stripped.startswith(f"{key}="):
+                lines[index] = f"{key}={remaining.pop(key)}"
+                break
+    lines.extend(f"{key}={value}" for key, value in remaining.items())
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return path
+
+
+@dataclass(frozen=True)
+class Settings:
+    mcp_url: str = DEFAULT_MCP_URL
+    periscope_token: str | None = None
+    model: str = DEFAULT_MODEL
+    openai_base_url: str | None = None
+    openai_api_key: str | None = None
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        load_env()
+        return cls(
+            mcp_url=_clean(os.environ.get("PERISCOPE_MCP_URL")) or DEFAULT_MCP_URL,
+            periscope_token=_clean(os.environ.get("PERISCOPE_AUTH_TOKEN")),
+            model=_clean(os.environ.get("I2A_MODEL")) or DEFAULT_MODEL,
+            openai_base_url=_clean(os.environ.get("OPENAI_BASE_URL")),
+            openai_api_key=_clean(os.environ.get("OPENAI_API_KEY")),
+        )

internet2agent/periscope.py

@@ -0,0 +1,416 @@
+"""Direct Python client for the Internet2 Periscope Looking Glass MCP server.
+
+The server exposes five tools:
+
+- ``lg_config``   - service limits (rate limit, max targets per request)
+- ``lg_devices``  - available devices (name/ID, location, type, platform)
+- ``lg_commands`` - supported commands and the platforms they run on
+- ``lg_filters``  - output filters (``include``/``exclude`` + regex pattern)
+- ``lg_execute``  - run a command on up to 10 devices
+
+``AsyncPeriscopeClient`` is the asyncio interface; ``PeriscopeClient`` is a
+synchronous facade that runs the MCP session on a background event-loop
+thread so one session can be reused across calls.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import json
+import threading
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator, Iterable
+
+from mcp import Client
+from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client
+
+try:
+    from mcp.shared.exceptions import MCPError
+except ImportError:  # pragma: no cover - name used by pre-2.1 releases
+    from mcp.shared.exceptions import McpError as MCPError
+
+from .config import Settings
+
+_CALL_TIMEOUT = 180.0
+_CONNECT_TIMEOUT = 30.0
+_CLOSE_GRACE = 15.0
+
+_LIST_TOOLS = object()  # queue sentinel: "run list_tools" (None means "shut down")
+
+
+class PeriscopeError(RuntimeError):
+    """Raised when the Periscope MCP server rejects or fails a request."""
+
+
+class _SessionClosedError(PeriscopeError):
+    """A queued call was abandoned because its session went away."""
+
+
+@asynccontextmanager
+async def _transport_with_headers(url: str, headers: dict[str, str]) -> AsyncIterator[Any]:
+    # mcp's Client(url) offers no header hook, so build the transport ourselves.
+    async with create_mcp_http_client(headers=headers) as http_client:
+        async with streamable_http_client(url, http_client=http_client) as streams:
+            yield streams
+
+
+def _decode(result: Any) -> Any:
+    """Decode a CallToolResult: structured JSON if present, else (JSON) text."""
+    structured = getattr(result, "structuredContent", None) or getattr(result, "structured_content", None)
+    if structured:
+        return structured
+    texts = [b.text for b in (result.content or []) if getattr(b, "type", None) == "text"]
+    text = "\n".join(texts)
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def _is_error(result: Any) -> bool:
+    return bool(getattr(result, "isError", False) or getattr(result, "is_error", False))
+
+
+class AsyncPeriscopeClient:
+    """Async MCP client for Periscope. Use as an async context manager.
+
+    ``url`` and ``auth_token`` default to the environment (``PERISCOPE_MCP_URL``,
+    ``PERISCOPE_AUTH_TOKEN``); the server currently requires no token.
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        auth_token: str | None = None,
+        settings: Settings | None = None,
+    ) -> None:
+        if url is None or auth_token is None:
+            settings = settings or Settings.from_env()
+        self.url = url or settings.mcp_url
+        self.auth_token = auth_token if auth_token is not None else settings.periscope_token
+        self._client: Client | None = None
+
+    async def __aenter__(self) -> "AsyncPeriscopeClient":
+        if self.auth_token:
+            target: Any = _transport_with_headers(
+                self.url, {"Authorization": f"Bearer {self.auth_token}"}
+            )
+        else:
+            target = self.url
+        client = Client(target)
+        await client.__aenter__()
+        self._client = client
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        client, self._client = self._client, None
+        if client is not None:
+            await client.__aexit__(exc_type, exc, tb)
+
+    async def call(self, tool: str, arguments: dict[str, Any] | None = None) -> Any:
+        """Call one MCP tool and return its decoded result."""
+        if self._client is None:
+            raise RuntimeError("not connected - use 'async with AsyncPeriscopeClient() as lg:'")
+        try:
+            result = await self._client.call_tool(tool, arguments or {})
+        except MCPError as exc:
+            # Protocol-level rejections (unknown device, invalid characters, rate
+            # limit) arrive as JSON-RPC errors, not isError results.
+            raise PeriscopeError(f"{tool} failed: {exc}") from exc
+        payload = _decode(result)
+        if _is_error(result):
+            raise PeriscopeError(f"{tool} failed: {payload}")
+        return payload
+
+    async def tools(self) -> list[dict[str, Any]]:
+        """The server's tool inventory: name, description, and input schema."""
+        if self._client is None:
+            raise RuntimeError("not connected - use 'async with AsyncPeriscopeClient() as lg:'")
+        result = await self._client.list_tools()
+        return [
+            {
+                "name": tool.name,
+                "description": tool.description or "",
+                "input_schema": getattr(tool, "input_schema", None)
+                or getattr(tool, "inputSchema", None),
+            }
+            for tool in result.tools
+        ]
+
+    async def config(self) -> Any:
+        """Service limits: rate limit and max targets per request."""
+        return await self.call("lg_config")
+
+    async def devices(self) -> Any:
+        """All available devices with name (ID), location, type, and platform."""
+        return await self.call("lg_devices")
+
+    async def commands(self) -> Any:
+        """Supported commands with help text and supported platforms."""
+        return await self.call("lg_commands")
+
+    async def filters(self) -> Any:
+        """Available output filters and the platforms they support."""
+        return await self.call("lg_filters")
+
+    async def execute(
+        self,
+        command: str,
+        targets: Iterable[str],
+        parameter: str | None = None,
+        filter: str | None = None,
+    ) -> Any:
+        """Run ``command`` on up to 10 devices.
+
+        ``targets`` must exactly match ``name`` values from :meth:`devices`.
+        ``parameter`` is appended to the command (e.g. a prefix for
+        ``show route``); ``filter`` is a filter name plus regex pattern,
+        e.g. ``"include bgp"`` or ``"exclude ^$"``.
+        """
+        arguments: dict[str, Any] = {"command": command, "targets": list(targets)}
+        if parameter is not None:
+            arguments["parameter"] = parameter
+        if filter is not None:
+            arguments["filter"] = filter
+        return await self.call("lg_execute", arguments)
+
+
+class PeriscopeClient:
+    """Synchronous facade over :class:`AsyncPeriscopeClient`.
+
+    The MCP session lives inside a single task on a background event loop
+    (mcp's transports use anyio cancel scopes, which must be entered and
+    exited by the same task). Calls are handed to that task over a queue.
+
+    Connects lazily on first use and reconnects automatically if the session
+    dies (server restart, dropped connection). Call :meth:`close` (or use it
+    as a context manager) to disconnect. Instances are not thread-safe.
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        auth_token: str | None = None,
+        settings: Settings | None = None,
+        call_timeout: float = _CALL_TIMEOUT,
+        connect_timeout: float = _CONNECT_TIMEOUT,
+    ) -> None:
+        self._client_args = (url, auth_token, settings)
+        self._call_timeout = call_timeout
+        self._connect_timeout = connect_timeout
+        self._lock = threading.Lock()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._queue: asyncio.Queue[Any] | None = None
+        self._worker: "concurrent.futures.Future[None] | None" = None
+        self._worker_exited: threading.Event | None = None
+
+    # -- session lifecycle ----------------------------------------------------
+
+    def _ensure_connected(self) -> None:
+        with self._lock:
+            if self._loop is not None:
+                return
+            loop = asyncio.new_event_loop()
+            thread = threading.Thread(target=loop.run_forever, name="periscope-mcp", daemon=True)
+            thread.start()
+
+            queue: asyncio.Queue[Any] = asyncio.Queue()
+            ready: "concurrent.futures.Future[None]" = concurrent.futures.Future()
+            exited = threading.Event()
+            worker = asyncio.run_coroutine_threadsafe(
+                self._session_worker(queue, ready, exited), loop
+            )
+            try:
+                ready.result(self._connect_timeout + 10)
+            except BaseException:
+                worker.cancel()
+                exited.wait(5)
+                loop.call_soon_threadsafe(loop.stop)
+                thread.join(timeout=5)
+                loop.close()
+                raise
+            self._loop = loop
+            self._thread = thread
+            self._queue = queue
+            self._worker = worker
+            self._worker_exited = exited
+
+    async def _session_worker(
+        self,
+        queue: "asyncio.Queue[Any]",
+        ready: "concurrent.futures.Future[None]",
+        exited: threading.Event,
+    ) -> None:
+        """Own the MCP session for its whole lifetime and serve queued calls."""
+        try:
+            client = AsyncPeriscopeClient(*self._client_args)
+            try:
+                await asyncio.wait_for(client.__aenter__(), self._connect_timeout)
+            except BaseException as exc:
+                if not ready.done():
+                    if isinstance(exc, Exception):
+                        ready.set_exception(exc)
+                    else:
+                        ready.set_exception(PeriscopeError(f"connect failed: {exc!r}"))
+                return
+            try:
+                ready.set_result(None)
+                while True:
+                    item = await queue.get()
+                    if item is None:
+                        return
+                    tool, arguments, future = item
+                    try:
+                        if tool is _LIST_TOOLS:
+                            coro = client.tools()
+                        else:
+                            coro = client.call(tool, arguments)
+                        result = await asyncio.wait_for(coro, self._call_timeout)
+                    except asyncio.CancelledError:
+                        # close() gave up waiting - fail the caller with a normal
+                        # exception and let the cancellation complete.
+                        if not future.done():
+                            future.set_exception(
+                                PeriscopeError("client closed while a call was in flight")
+                            )
+                        raise
+                    except asyncio.TimeoutError:
+                        if not future.done():
+                            future.set_exception(
+                                TimeoutError(
+                                    f"Periscope call timed out after {self._call_timeout:g}s"
+                                )
+                            )
+                    except Exception as exc:  # per-call errors keep the session alive
+                        if not future.done():
+                            future.set_exception(exc)
+                    except BaseException as exc:
+                        if not future.done():
+                            future.set_exception(exc)
+                        raise
+                    else:
+                        if not future.done():
+                            future.set_result(result)
+            finally:
+                try:
+                    await asyncio.wait_for(client.__aexit__(None, None, None), 15)
+                except BaseException:
+                    pass  # best effort - the transport may already be gone
+        finally:
+            # Fail anything still queued so callers don't wait out their timeout,
+            # then signal the sync side that this session is over.
+            while True:
+                try:
+                    item = queue.get_nowait()
+                except asyncio.QueueEmpty:
+                    break
+                if item is not None and not item[2].done():
+                    item[2].set_exception(_SessionClosedError("Periscope session closed"))
+            exited.set()
+
+    def _call(self, tool: Any, arguments: dict[str, Any] | None = None, *, _retry: bool = True) -> Any:
+        self._ensure_connected()
+        exited = self._worker_exited
+        if exited is not None and exited.is_set():
+            # The session died since the last call (server restart, dropped
+            # connection). Reap it and reconnect once.
+            self.close()
+            self._ensure_connected()
+
+        loop, queue = self._loop, self._queue
+        if loop is None or queue is None:
+            raise PeriscopeError("client is closed")
+        future: "concurrent.futures.Future[Any]" = concurrent.futures.Future()
+        loop.call_soon_threadsafe(queue.put_nowait, (tool, arguments, future))
+        try:
+            # The worker enforces the real per-call timeout; this is a backstop.
+            return future.result(self._call_timeout + 15)
+        except _SessionClosedError:
+            # Raced a dying session: the call was queued while the worker was
+            # unwinding. Reap it and retry once on a fresh session.
+            if not _retry:
+                raise
+            self.close()
+            return self._call(tool, arguments, _retry=False)
+        except (TimeoutError, concurrent.futures.TimeoutError) as exc:
+            if not future.done():
+                future.cancel()
+            # Normalize to builtin TimeoutError (they differ on Python 3.10).
+            raise TimeoutError(
+                str(exc) or f"Periscope call timed out after {self._call_timeout:g}s"
+            ) from None
+
+    def close(self) -> None:
+        """Disconnect and stop the background loop. Safe to call twice."""
+        with self._lock:
+            loop, thread, queue, worker, exited = (
+                self._loop,
+                self._thread,
+                self._queue,
+                self._worker,
+                self._worker_exited,
+            )
+            self._loop = self._thread = self._queue = self._worker = self._worker_exited = None
+        if loop is None:
+            return
+        try:
+            loop.call_soon_threadsafe(queue.put_nowait, None)
+            if not exited.wait(_CLOSE_GRACE):
+                worker.cancel()  # a call is stuck in flight - force the session down
+                exited.wait(10)
+        finally:
+            loop.call_soon_threadsafe(loop.stop)
+            thread.join(timeout=5)
+            loop.close()
+
+    def __enter__(self) -> "PeriscopeClient":
+        self._ensure_connected()
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()
+
+    # -- Looking Glass tools --------------------------------------------------
+
+    def call(self, tool: str, arguments: dict[str, Any] | None = None) -> Any:
+        """Call an arbitrary Periscope MCP tool and return its decoded result."""
+        if not isinstance(tool, str) or not tool:
+            raise PeriscopeError(f"invalid tool name: {tool!r}")
+        return self._call(tool, arguments)
+
+    def tools(self) -> list[dict[str, Any]]:
+        """The server's tool inventory: name, description, and input schema."""
+        return self._call(_LIST_TOOLS)
+
+    def config(self) -> Any:
+        """Service limits: rate limit and max targets per request."""
+        return self.call("lg_config")
+
+    def devices(self) -> Any:
+        """All available devices with name (ID), location, type, and platform."""
+        return self.call("lg_devices")
+
+    def commands(self) -> Any:
+        """Supported commands with help text and supported platforms."""
+        return self.call("lg_commands")
+
+    def filters(self) -> Any:
+        """Available output filters and the platforms they support."""
+        return self.call("lg_filters")
+
+    def execute(
+        self,
+        command: str,
+        targets: Iterable[str],
+        parameter: str | None = None,
+        filter: str | None = None,
+    ) -> Any:
+        """Run ``command`` on up to 10 devices. See AsyncPeriscopeClient.execute."""
+        arguments: dict[str, Any] = {"command": command, "targets": list(targets)}
+        if parameter is not None:
+            arguments["parameter"] = parameter
+        if filter is not None:
+            arguments["filter"] = filter
+        return self.call("lg_execute", arguments)

internet2agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: internet2agent
+Version: 0.1.0
+Summary: Python client and LLM agent for the Internet2 Periscope Looking Glass MCP server
+Author-email: AstralDeep <armstrongsam25@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AstralDeep/internet2agent
+Project-URL: Repository, https://github.com/AstralDeep/internet2agent
+Project-URL: Issues, https://github.com/AstralDeep/internet2agent/issues
+Keywords: internet2,mcp,looking-glass,network,bgp,traceroute,llm,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.50
+Requires-Dist: mcp>=2.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# internet2agent
+
+Python interface and LLM agent for the **Internet2 Periscope Looking Glass MCP
+server** (`https://periscope.ns.internet2.edu/mcp`) - the service announced in
+[Internet2's MCP server post](https://internet2.edu/new-mcp-server-lets-re-community-connect-their-ai-agent/),
+documented in the [Console docs](https://console.internet2.edu/docs/looking-glass.html#mcp-server).
+
+Two ways in, no GUI:
+
+1. **Direct client** (`PeriscopeClient` / `AsyncPeriscopeClient`) - typed Python
+   access to the five Looking Glass tools. **Works today with zero
+   credentials** (the server is currently open; verified live).
+2. **LLM agent** (`Internet2Agent`) - natural-language questions answered by
+   any **OpenAI-compatible** model (OpenAI, Ollama, vLLM, LM Studio,
+   OpenRouter, ...). The agent pulls the tool schemas from the MCP server,
+   hands them to the model as function tools, executes the model's tool calls
+   against Periscope, and loops until it has an answer.
+
+## Setup
+
+```powershell
+cd Y:\WORK\MCP\internet2agent
+.venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Then configure your LLM in [.env](.env) (gitignored; template in
+[.env.example](.env.example)):
+
+| Variable | Needed for | Notes |
+|---|---|---|
+| `OPENAI_BASE_URL` | `ask` / `chat` / `Internet2Agent` | unset = api.openai.com; Ollama: `http://localhost:11434/v1`; LM Studio: `http://localhost:1234/v1` |
+| `OPENAI_API_KEY` | same | optional for local endpoints that don't check keys |
+| `I2A_MODEL` | same | model name to request (default `gpt-4o` - set to what your endpoint serves) |
+| `PERISCOPE_MCP_URL` | optional | defaults to the public endpoint |
+| `PERISCOPE_AUTH_TOKEN` | **not yet** | future Internet2 credential; sent as `Authorization: Bearer ...` once set |
+
+## CLI
+
+Direct Looking Glass (no credentials):
+
+```powershell
+internet2agent info                # service limits (rate limit, max targets)
+internet2agent devices             # device inventory (name, location, platform)
+internet2agent commands            # supported commands per platform
+internet2agent filters             # output filters (include/exclude + regex)
+internet2agent exec "show bgp" -t rtr1 rtr2 -p summary -f "include Established"
+```
+
+Add `--json` to any of the above for raw JSON. `i2a` is a short alias for
+`internet2agent`.
+
+LLM agent:
+
+```powershell
+internet2agent ask "Is BGP healthy on the Chicago routers?"
+internet2agent chat                # interactive multi-turn session
+```
+
+If no LLM endpoint is configured yet, `ask`/`chat` walk you through a one-time
+setup (base URL, API key, model) and offer to save it to `.env`.
+
+Tool calls are echoed as `[lg_execute {...}]` lines while the agent works.
+
+## Python API
+
+```python
+from internet2agent import PeriscopeClient
+
+with PeriscopeClient() as lg:
+    devices = lg.devices()                       # [{"name": ..., "platform": ...}, ...]
+    result = lg.execute("show bgp", ["rtr1"], parameter="summary")
+```
+
+Async variant:
+
+```python
+from internet2agent import AsyncPeriscopeClient
+
+async with AsyncPeriscopeClient() as lg:
+    print(await lg.config())
+```
+
+Agent:
+
+```python
+from internet2agent import Internet2Agent
+
+with Internet2Agent() as agent:                   # reads .env
+    print(agent.ask("Which devices are in Seattle?"))
+    print(agent.ask("Run a traceroute from one of them to 8.8.8.8"))  # follow-ups keep context
+```
+
+## Service constraints (from the server)
+
+- Max **10 target devices** per `lg_execute`; commands must match documented
+  syntax exactly (no abbreviations).
+- Rate limit: **60 requests/min** (check live with `internet2agent info`).
+- `parameter` is appended to the command (`show route` + `10.0.0.0/8`);
+  `filter` is a filter name plus case-sensitive regex (`include bgp`,
+  `exclude ^$`).
+- Commands/filters are platform-specific - the agent (and you) should check
+  `commands`/`filters` against each device's `platform` before executing.
+
+## Tests
+
+```powershell
+pytest              # unit tests (offline, mocked)
+pytest -m network   # live smoke tests against the real Periscope server
+```
+
+## Releasing to PyPI
+
+Publishing runs through GitHub Actions with [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+(no API tokens stored anywhere). One-time setup:
+
+1. On [pypi.org](https://pypi.org) -> your account -> Publishing -> "Add a new
+   pending publisher": project `internet2agent`, owner `AstralDeep`, repository
+   `internet2agent`, workflow `publish.yml`, environment `pypi`.
+2. On GitHub -> repo Settings -> Environments -> create an environment named `pypi`.
+
+Then, for each release: bump `version` in `pyproject.toml`, push, and publish a
+GitHub release with a `vX.Y.Z` tag - the workflow builds and uploads.
+
+Manual alternative: `python -m build && twine upload dist/*` with a PyPI API token.
+
+## Notes
+
+- The agent requires an endpoint that supports OpenAI-style **function/tool
+  calling**; pick a tool-capable model (most current ones are).
+- The agent caps each question at 25 LLM round-trips as a runaway guard
+  (`Internet2Agent(max_steps=...)` to change).
+- Tool errors (unknown device, bad syntax, timeouts) are fed back to the model
+  as `ERROR:` tool results so it can correct itself instead of crashing.

internet2agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+internet2agent/__init__.py,sha256=pCWXEHIb81VA9AFoM4ducIveR7YxR3Kq-PKFfr3qcgQ,452
+internet2agent/agent.py,sha256=z4n35eony0IEYOmzJ5aqdAoIWntgBapP7FQomai7py4,8446
+internet2agent/cli.py,sha256=DlB6E2ni1ZwhuimDoBrafXkjxYODaFqPe4vtj8jhZS0,10358
+internet2agent/config.py,sha256=HK0Qd6wspGAaoTvlpf1IxzrIqo0U_3QhzKBEih0-wSU,3166
+internet2agent/periscope.py,sha256=W_SKByiD6ObXBKx1l-epU-r_inHUpJokzsA7AtxUDRk,16706
+internet2agent-0.1.0.dist-info/licenses/LICENSE,sha256=cx4pn-FOnkf2uUAEabQJYqxV8KAV6bQmCuDBKAp1MfA,1067
+internet2agent-0.1.0.dist-info/METADATA,sha256=DHitxbcVWMMXJXLwxZ6zRDyHEUwocOukBtb2kJyfPHc,6580
+internet2agent-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+internet2agent-0.1.0.dist-info/entry_points.txt,sha256=JXMiWqD3SvmlRiGdtlloPaIFOfODTPq78XJG1uESFoI,89
+internet2agent-0.1.0.dist-info/top_level.txt,sha256=I_pGlG8__dvT5NchwzgzuwqlajeIxPYhsG1RLZlkjqc,15
+internet2agent-0.1.0.dist-info/RECORD,,

internet2agent-0.1.0.dist-info/WHEEL

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

internet2agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+i2a = internet2agent.cli:main
+internet2agent = internet2agent.cli:main

internet2agent-0.1.0.dist-info/licenses/LICENSE

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

internet2agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+internet2agent