vis-agent 0.2.2__tar.gz → 0.2.3__tar.gz

{vis_agent-0.2.2 → vis_agent-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.2.2
+Version: 0.2.3
 Summary: The Vis Python SDK — author extensions and control local or remote engines.
 Project-URL: Homepage, https://vis.blockether.com
 Project-URL: Documentation, https://vis.blockether.com
@@ -28,6 +28,11 @@ Python SDK for Vis extensions and agent sessions.
 pip install vis-agent
 ```
 
-Requires Python 3.11+. The Vis executable is installed separately.
+Requires Python 3.11+. Install the Vis executable and configure a provider
+separately for local use.
 
-[Documentation](https://vis.blockether.com)
+- [Python SDK guide](https://vis.blockether.com/python-sdk.html) — run a local
+  agent, continue a conversation or connect to a shared gateway. The new
+  `Agent(project=".")` API requires the source SDK, not PyPI `0.2.2`.
+- [Extension guide](https://vis.blockether.com/extending.html) — add tools to Vis.
+- [Documentation](https://vis.blockether.com) — browse all guides and reference pages.

vis_agent-0.2.3/README.md

@@ -0,0 +1,16 @@
+# vis-agent
+
+Python SDK for Vis extensions and agent sessions.
+
+```sh
+pip install vis-agent
+```
+
+Requires Python 3.11+. Install the Vis executable and configure a provider
+separately for local use.
+
+- [Python SDK guide](https://vis.blockether.com/python-sdk.html) — run a local
+  agent, continue a conversation or connect to a shared gateway. The new
+  `Agent(project=".")` API requires the source SDK, not PyPI `0.2.2`.
+- [Extension guide](https://vis.blockether.com/extending.html) — add tools to Vis.
+- [Documentation](https://vis.blockether.com) — browse all guides and reference pages.

{vis_agent-0.2.2 → vis_agent-0.2.3}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vis-agent"
-version = "0.2.2"
+version = "0.2.3"
 description = "The Vis Python SDK — author extensions and control local or remote engines."
 readme = "README.md"
 requires-python = ">=3.11"

{vis_agent-0.2.2 → vis_agent-0.2.3}/src/blockether/vis/engine/__init__.py

@@ -1,9 +1,11 @@
-"""Explicit Vis engine clients, lifecycle records, streams and transport errors.
+"""Vis agents, engine clients, lifecycle records, streams and transport errors.
 
-``GatewayClient`` connects to an existing gateway; ``LocalEngine`` owns a local
-stdio process. Importing either starts nothing and never binds an extension host.
+``Agent`` runs one conversation locally or through an existing gateway.
+``GatewayClient`` manages gateway sessions; ``LocalEngine`` owns a local stdio
+process. Importing these starts nothing and never binds an extension host.
 """
 
+from ._agent import Agent
 from ._client import (
     Event,
     Events,
@@ -33,6 +35,7 @@ from ._council import (
 from ._local import LocalEngine
 
 __all__ = [
+    "Agent",
     "Council",
     "CouncilEntry",
     "CouncilKind",

vis_agent-0.2.3/src/blockether/vis/engine/_agent.py

@@ -0,0 +1,105 @@
+"""One conversation using an owned stdio engine or an existing HTTP gateway."""
+
+from pathlib import Path, PurePosixPath
+
+from ._client import GatewayClient, Session, TransportError, Turn
+from ._local import LocalEngine
+
+
+class Agent:
+    """Run tasks locally, or connect to a separately running gateway.
+
+    Agent() resolves the existing local project directory (default: ".") at
+    construction. Context entry, send(), run() or session starts a private
+    LocalEngine and one conversation, without an HTTP listener. close() stops
+    that process and discards its temporary session database, not file edits.
+    Environment, provider credentials and extensions are inherited. Linux/macOS.
+
+    With gateway_url, project must be an absolute POSIX path on that gateway;
+    it is never resolved or checked on the client machine. No local engine is
+    needed. The agent creates one app-channel session through GatewayClient.
+    close() releases the client lease, not the saved session or remote work.
+    The URL and optional bearer token are explicit; no environment discovery.
+
+    executable (launcher path or argv) and startup_timeout are local-only.
+    timeout bounds transport operations in either mode. Instances use one
+    calling thread. Use GatewayClient directly to resume or manage sessions.
+    """
+
+    def __init__(
+        self,
+        project=".",
+        *,
+        gateway_url=None,
+        token=None,
+        executable="vis-agent",
+        timeout=30,
+        startup_timeout=120,
+    ):
+        if gateway_url is None:
+            if token is not None:
+                raise ValueError("token requires gateway_url")
+            self.project = Path(project).resolve(strict=True)
+            if not self.project.is_dir():
+                raise NotADirectoryError(str(self.project))
+            self._client = LocalEngine(
+                executable=executable,
+                root=self.project,
+                timeout=timeout,
+                startup_timeout=startup_timeout,
+            )
+            self._session_options = {"root": str(self.project)}
+        else:
+            if executable != "vis-agent" or startup_timeout != 120:
+                raise ValueError("executable and startup_timeout are local-only")
+            self.project = PurePosixPath(project)
+            if not self.project.is_absolute():
+                raise ValueError("project must be an absolute path on the gateway")
+            self._client = GatewayClient(gateway_url, token=token, timeout=timeout)
+            self._session_options = {"root": str(self.project), "channel": "app"}
+        self._session = None
+        self._closed = False
+
+    @property
+    def session(self) -> Session:
+        """The same conversation for all requests; connects on first access."""
+        if self._closed:
+            raise TransportError("agent is closed")
+        if self._session is None:
+            try:
+                self._client.connect()
+                self._session = self._client.create_session(**self._session_options)
+            except BaseException:
+                self.close()
+                raise
+        return self._session
+
+    def send(self, request: str, **options) -> Turn:
+        """Submit a request, returning a Turn for progress, waiting or cancellation.
+
+        Options are passed to Session.send(), including provider, model and
+        idempotency_key. Follow-up requests use this agent's existing session.
+        """
+        return self.session.send(request, **options)
+
+    def run(self, request: str, *, timeout=300, **options):
+        """Submit and wait, returning the canonical turn record, not a text string.
+
+        Inspect status: failed, cancelled or suspended records are returned too.
+        A wait timeout raises VisTimeout without cancelling the turn. Context
+        exit stops unfinished local work; remote work can outlive the client.
+        """
+        return self.send(request, **options).wait(timeout=timeout)
+
+    def close(self):
+        """Close the owned process or gateway client, never a remote session or service."""
+        if not self._closed:
+            self._closed = True
+            self._client.close()
+
+    def __enter__(self):
+        _ = self.session
+        return self
+
+    def __exit__(self, *_):
+        self.close()

vis_agent-0.2.3/tests/test_agent.py

@@ -0,0 +1,216 @@
+"""Agent lifecycle and delegation; real transports live in test_sdk_guide."""
+
+from unittest.mock import Mock
+
+import blockether.vis.engine as engine
+import pytest
+
+
+@pytest.fixture
+def local(monkeypatch):
+    factory = Mock()
+    monkeypatch.setattr("blockether.vis.engine._agent.LocalEngine", factory)
+    return factory
+
+
+def test_default_project_is_resolved_before_chdir(local, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    agent = engine.Agent()
+    monkeypatch.chdir(tmp_path.parent)
+    assert agent.project == tmp_path.resolve()
+    local.assert_called_once_with(
+        executable="vis-agent", root=tmp_path.resolve(), timeout=30, startup_timeout=120
+    )
+    local.return_value.connect.assert_not_called()
+    with agent:
+        assert agent.session is local.return_value.create_session.return_value
+        local.return_value.create_session.assert_called_once_with(
+            root=str(tmp_path.resolve())
+        )
+    local.return_value.close.assert_called_once_with()
+
+
+def test_followups_and_options_use_one_conversation(local, tmp_path):
+    with engine.Agent(tmp_path, executable=["custom-vis", "--jvm"]) as agent:
+        conversation = agent.session
+        result = agent.run("First", timeout=42, provider="provider", model="model")
+        conversation.send.assert_called_once_with(
+            "First", provider="provider", model="model"
+        )
+        conversation.send.return_value.wait.assert_called_once_with(timeout=42)
+        assert result is conversation.send.return_value.wait.return_value
+        turn = agent.send("Follow up", idempotency_key="same-request")
+        assert turn is conversation.send.return_value
+        conversation.send.assert_called_with(
+            "Follow up", idempotency_key="same-request"
+        )
+    local.return_value.connect.assert_called_once_with()
+    local.return_value.create_session.assert_called_once()
+
+
+@pytest.mark.parametrize("status", ["completed", "failed", "cancelled", "suspended"])
+def test_run_preserves_the_canonical_turn_record(local, tmp_path, status):
+    result = {"status": status, "content": [], "turn_id": "turn"}
+    local.return_value.create_session.return_value.send.return_value.wait.return_value = result
+    with engine.Agent(tmp_path) as agent:
+        assert agent.run("Request") is result
+
+
+@pytest.mark.parametrize("operation", ["connect", "create_session"])
+def test_startup_failure_closes_engine_and_prevents_reuse(local, tmp_path, operation):
+    getattr(local.return_value, operation).side_effect = engine.TransportError(
+        "startup"
+    )
+    agent = engine.Agent(tmp_path)
+    with pytest.raises(engine.TransportError, match="startup"):
+        with agent:
+            pytest.fail("startup should not succeed")
+    local.return_value.close.assert_called_once_with()
+    with pytest.raises(engine.TransportError, match="closed"):
+        agent.send("retry")
+    agent.close()
+    local.return_value.close.assert_called_once_with()
+
+
+def test_close_without_start_and_body_exception(local, tmp_path):
+    agent = engine.Agent(tmp_path)
+    agent.close()
+    agent.close()
+    local.return_value.connect.assert_not_called()
+    local.return_value.close.assert_called_once_with()
+    with pytest.raises(engine.TransportError, match="closed"):
+        with agent:
+            pass
+    local.reset_mock()
+    with pytest.raises(RuntimeError, match="body"):
+        with engine.Agent(tmp_path):
+            raise RuntimeError("body")
+    local.return_value.close.assert_called_once_with()
+
+
+def test_wait_timeout_does_not_cancel_the_turn(local, tmp_path):
+    with engine.Agent(tmp_path) as agent:
+        turn = agent.session.send.return_value
+        turn.wait.side_effect = engine.VisTimeout("deadline")
+        with pytest.raises(engine.VisTimeout, match="deadline"):
+            agent.run("Request", timeout=0.1)
+        turn.cancel.assert_not_called()
+        local.return_value.close.assert_not_called()
+    local.return_value.close.assert_called_once_with()
+
+
+def test_project_must_be_an_existing_directory(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        engine.Agent(tmp_path / "missing")
+    file = tmp_path / "file"
+    file.touch()
+    with pytest.raises(NotADirectoryError):
+        engine.Agent(file)
+
+
+def test_missing_launcher_has_no_surviving_process(tmp_path):
+    agent = engine.Agent(tmp_path, executable=str(tmp_path / "missing"))
+    with pytest.raises(engine.TransportError):
+        with agent:
+            pass
+    agent.close()
+
+
+@pytest.fixture
+def remote(monkeypatch):
+    factory = Mock()
+    monkeypatch.setattr("blockether.vis.engine._agent.GatewayClient", factory)
+    return factory
+
+
+def test_remote_agent_needs_no_local_project_or_engine(local, remote):
+    agent = engine.Agent(
+        "/srv/vis-project",
+        gateway_url="https://gateway.example.com",
+        token="test-token",
+        timeout=12,
+    )
+    assert str(agent.project) == "/srv/vis-project"
+    local.assert_not_called()
+    remote.assert_called_once_with(
+        "https://gateway.example.com", token="test-token", timeout=12
+    )
+    remote.return_value.connect.assert_not_called()
+    with agent:
+        conversation = agent.session
+        remote.return_value.create_session.assert_called_once_with(
+            root="/srv/vis-project", channel="app"
+        )
+        result = agent.run("First", timeout=42, provider="provider", model="model")
+        assert result is conversation.send.return_value.wait.return_value
+        conversation.send.assert_called_once_with(
+            "First", provider="provider", model="model"
+        )
+        conversation.send.return_value.wait.assert_called_once_with(timeout=42)
+        assert agent.send("Follow up") is conversation.send.return_value
+        conversation.send.assert_called_with("Follow up")
+    remote.return_value.connect.assert_called_once_with()
+    remote.return_value.create_session.assert_called_once()
+    remote.return_value.close.assert_called_once_with()
+    conversation.delete.assert_not_called()
+    conversation.send.return_value.cancel.assert_not_called()
+    agent.close()
+    remote.return_value.close.assert_called_once_with()
+    with pytest.raises(engine.TransportError, match="closed"):
+        agent.send("Retry")
+
+
+@pytest.mark.parametrize("operation", ["connect", "create_session"])
+def test_remote_startup_failure_releases_client(remote, operation):
+    getattr(remote.return_value, operation).side_effect = engine.TransportError(
+        "startup"
+    )
+    agent = engine.Agent("/srv/vis-project", gateway_url="https://gateway.example.com")
+    with pytest.raises(engine.TransportError, match="startup"):
+        with agent:
+            pytest.fail("startup should not succeed")
+    remote.return_value.close.assert_called_once_with()
+    with pytest.raises(engine.TransportError, match="closed"):
+        agent.run("Retry")
+
+
+def test_remote_wait_timeout_and_context_error_only_close_client(remote):
+    with pytest.raises(engine.VisTimeout, match="deadline"):
+        with engine.Agent(
+            "/srv/vis-project", gateway_url="https://gateway.example.com"
+        ) as agent:
+            turn = agent.session.send.return_value
+            turn.wait.side_effect = engine.VisTimeout("deadline")
+            agent.run("Request", timeout=0.1)
+    turn.cancel.assert_not_called()
+    remote.return_value.close.assert_called_once_with()
+    remote.return_value.create_session.return_value.delete.assert_not_called()
+
+
+def test_remote_close_before_connect(remote):
+    agent = engine.Agent("/srv/vis-project", gateway_url="https://gateway.example.com")
+    agent.close()
+    agent.close()
+    remote.return_value.connect.assert_not_called()
+    remote.return_value.close.assert_called_once_with()
+
+
+@pytest.mark.parametrize("project", [".", "relative/project", "", "~/project"])
+def test_remote_project_must_be_explicit_absolute_path(local, project):
+    with pytest.raises(ValueError, match="absolute.*gateway"):
+        engine.Agent(project, gateway_url="https://gateway.example.com")
+    local.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    "options",
+    [
+        {"token": "test-token"},
+        {"gateway_url": "https://gateway.example.com", "executable": "custom-vis"},
+        {"gateway_url": "https://gateway.example.com", "startup_timeout": 10},
+    ],
+)
+def test_mixed_transport_options_are_rejected(local, tmp_path, options):
+    with pytest.raises(ValueError):
+        engine.Agent(tmp_path, **options)
+    local.assert_not_called()

{vis_agent-0.2.2 → vis_agent-0.2.3}/tests/test_engine.py

@@ -247,6 +247,7 @@ def sdk_fixture(
     council=False,
     tool_code=None,
     before_reply=None,
+    project_extensions=None,
 ):
     raw = os.environ.get("VIS_TEST_LOCAL_COMMAND")
     if not raw:
@@ -258,6 +259,8 @@ def sdk_fixture(
     extensions = work / ".vis" / "extensions"
     extensions.mkdir(parents=True)
     (extensions / "fixture.py").write_text(EXTENSION)
+    for name, source in (project_extensions or {}).items():
+        (extensions / name).write_text(source)
     monkeypatch.setenv("HOME", str(home))
     monkeypatch.setenv("JAVA_TOOL_OPTIONS", f"-Duser.home={home}")
     monkeypatch.delenv("VIS_GATEWAY_URL", raising=False)