internet2agent 0.1.0__tar.gz

internet2agent-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,134 @@
+# 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/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "internet2agent"
+version = "0.1.0"
+description = "Python client and LLM agent for the Internet2 Periscope Looking Glass MCP server"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "AstralDeep", email = "armstrongsam25@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["internet2", "mcp", "looking-glass", "network", "bgp", "traceroute", "llm", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "Intended Audience :: Telecommunications Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Networking :: Monitoring",
+]
+dependencies = [
+    "openai>=1.50",
+    "mcp>=2.0",
+    "python-dotenv>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/AstralDeep/internet2agent"
+Repository = "https://github.com/AstralDeep/internet2agent"
+Issues = "https://github.com/AstralDeep/internet2agent/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+internet2agent = "internet2agent.cli:main"
+i2a = "internet2agent.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = [
+    "network: tests that hit the live Periscope MCP server (run with: pytest -m network)",
+]
+addopts = "-m 'not network'"
+testpaths = ["tests"]

internet2agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

internet2agent-0.1.0/src/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-0.1.0/src/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:]