vectros-sdk 2.0.0__tar.gz

vectros_sdk-2.0.0/LICENSE

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

vectros_sdk-2.0.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: vectros-sdk
+Version: 2.0.0
+Summary: Build AI agents that run on the AIOS kernel (Vectros OS)
+Author: The Vectros authors
+License-Expression: MIT
+Project-URL: Repository, https://github.com/vectros/vectros-sdk
+Project-URL: Issues, https://github.com/vectros/vectros-sdk/issues
+Keywords: agents,llm,aios,kernel,vectros
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# Vectros SDK
+
+Build AI agents that run on the AIOS kernel (`aios.ko`) in a few lines, then
+deploy them to a Vectros OS host.
+
+```python
+from vectros import Agent, tool
+
+@tool
+def weather(city: str) -> str:
+    """Current weather for a city."""
+    return f"{city}: 31 C, clear sky"
+
+agent = Agent("helper", tools=[weather])
+print(agent.run("What is the weather in Pune?"))
+```
+
+The SDK registers the agent with the kernel, sets up its cores, runs the tool
+loop, streams output, emits traces and unregisters the agent at exit.
+
+## What the kernel gives every agent
+
+- **Scheduling and quotas.** Every model call is an AIOS LLM syscall. The kernel
+  queues it fairly with other agents and enforces per-agent limits.
+- **Model allowlist.** `model=` must be on the administrator's allowlist.
+- **Tool control.** Every tool call is a kernel syscall, including your own
+  `@tool` functions. The kernel checks permission, applies the deadline and
+  records the call.
+- **Approvals.** Kernel tools flagged as side-effecting, and `@tool(approval=True)`
+  functions, are held until the owner approves them, through `approve=` or in
+  AIOS Manager.
+- **Stable identity.** The agent ID comes from your UID and the agent name.
+  Only one agent with that name runs per user, and its storage survives
+  restarts.
+- **Tracing.** When the administrator enables tracing for the agent
+  (`sudo aiosctl trace enable <agent-id>`), runs appear in AIOS Trace with
+  kernel queue and lease timings. Tracing is off by default.
+- **Storage.** `agent.storage` is private, versioned and quota-limited.
+
+The SDK needs `aios.ko` loaded and `libaios.so` installed. There is no
+userspace fallback. Without the kernel, the SDK raises `KernelUnavailable`.
+
+## Requirements
+
+- Python 3.11 or later
+- `aios.ko` loaded, with the LLM worker running. Storage and kernel tools also
+  need the storage and tool workers.
+- Your user in the `aios` group
+- `libaios.so` in `/usr/lib`, or its path in `VECTROS_LIBAIOS`
+
+```sh
+pip install vectros-sdk
+```
+
+The package installs as `vectros-sdk` and imports as `vectros`. On Vectros OS
+it is preinstalled as the `python-vectros` package.
+
+## Agent
+
+```python
+Agent(
+    name,                 # shown in AIOS Manager and Trace
+    model=None,           # default: the LLM worker's model
+    tools=[],             # @tool functions and/or kernel tool names
+    system=None,          # system prompt
+    session=None,         # keep the conversation across runs and restarts
+    max_steps=10,         # maximum model calls per run
+    approve=None,         # approve(tool_name, args) -> bool
+    timeout=120,          # seconds per model or tool call
+    tool_protocol="native",  # or "json" for models without function calling
+)
+```
+
+| Call | Result |
+| --- | --- |
+| `agent.run(prompt)` | Final answer as `str` |
+| `agent.stream(prompt)` | `Event`s: `token`, `tool_call`, `tool_result`, `answer` |
+| `agent.storage.write(path, data)` / `.read(path)` | Kernel storage |
+| `agent.reset()` | Forget the session |
+| `agent.close()` or `with Agent(...)` | Unregister now, not at exit |
+
+```python
+for event in agent.stream("Plan my day"):
+    if event.kind == "token":
+        print(event.data, end="")
+```
+
+## Tools
+
+```python
+@tool
+def search(query: str, limit: int = 5) -> list[str]:
+    """Search the docs.
+
+    Args:
+        query: What to look for.
+    """
+
+@tool(approval=True)          # runs only if approve() returns True
+def send_email(to: str, body: str) -> str: ...
+
+agent = Agent("ops", tools=[search, send_email, "search_web"], approve=ask_terminal)
+```
+
+- The SDK builds the parameter schema from type hints, and descriptions from
+  the docstring and its `Args:` section.
+- A string names a tool registered in the kernel, for example an admin tool or
+  an MCP tool such as `github__create_issue`. These run in the AIOS tool worker.
+- `@tool` functions run in the agent's own process. Each call is first
+  submitted as a kernel client tool call (ABI 4.3). The function runs only
+  after the kernel hands the call back, which can be after owner approval.
+- When a tool raises an error, the error goes back to the model, and the model
+  can try again.
+- Tool calls use the model's native function calling. For models without
+  function calling, set `tool_protocol="json"`: the agent then asks for JSON
+  replies.
+
+## Sessions
+
+```python
+agent = Agent("support", session="customer-42")
+```
+
+History is stored in `$XDG_STATE_HOME/vectros/sessions/<agent>/<session>.json`
+and survives restarts. Only user prompts and final answers are kept, up to 40
+messages.
+
+## CLI
+
+```sh
+vectros init helper         # helper/vectros.toml + helper/agent.py
+cd helper
+vectros chat                # interactive; or: vectros chat "one question"
+vectros run                 # run the entry script
+vectros deploy me@host      # deploy to a Vectros OS host
+vectros logs -f             # follow the deployed agent's journal
+vectros status
+vectros stop
+```
+
+`vectros.toml`:
+
+```toml
+[agent]
+name = "helper"
+entry = "agent.py"     # script run by `vectros run` and by the service
+object = "agent"       # Agent variable used by `vectros chat`
+
+[deploy]
+host = "me@vectros-host"
+```
+
+`vectros deploy` does the following:
+
+1. Checks that the host has `/dev/aios` and the `vectros` package.
+2. Copies the project with rsync to `~/.local/share/vectros/agents/<name>`.
+3. Creates a venv with system site packages and installs `requirements.txt`
+   if the project has one.
+4. Starts the systemd user service `vectros-agent@<name>`, which runs
+   `python -m vectros run`.
+
+To keep the agent running after you log out, run `loginctl enable-linger` on
+the host.
+
+## Tests
+
+```sh
+pytest                         # unit tests, fake kernel
+VECTROS_E2E=1 pytest -m kernel # real aios.ko and workers
+```
+
+## Kernel versions
+
+The SDK needs ABI 4. Kernels before 4.3 still work with these limits:
+
+- Agent IDs are random, so `agent.storage` data is not readable after a restart.
+- `@tool` functions run in-process without kernel mediation. The SDK enforces
+  `approval=True` itself and denies the call when no `approve=` is set.
+
+## Limits
+
+- The kernel sees that a `@tool` function ran, but it cannot see what the
+  function does inside the agent process.
+- Sessions are local files on the host, not kernel storage. Kernel storage
+  files are limited to 64 KiB.
+- Native tool calls need the LLM worker that returns the tool envelope
+  (vectros-kernel with ABI 4.3). An older worker returns plain text, so the
+  agent treats the reply as the final answer.

vectros_sdk-2.0.0/README.md

@@ -0,0 +1,188 @@
+# Vectros SDK
+
+Build AI agents that run on the AIOS kernel (`aios.ko`) in a few lines, then
+deploy them to a Vectros OS host.
+
+```python
+from vectros import Agent, tool
+
+@tool
+def weather(city: str) -> str:
+    """Current weather for a city."""
+    return f"{city}: 31 C, clear sky"
+
+agent = Agent("helper", tools=[weather])
+print(agent.run("What is the weather in Pune?"))
+```
+
+The SDK registers the agent with the kernel, sets up its cores, runs the tool
+loop, streams output, emits traces and unregisters the agent at exit.
+
+## What the kernel gives every agent
+
+- **Scheduling and quotas.** Every model call is an AIOS LLM syscall. The kernel
+  queues it fairly with other agents and enforces per-agent limits.
+- **Model allowlist.** `model=` must be on the administrator's allowlist.
+- **Tool control.** Every tool call is a kernel syscall, including your own
+  `@tool` functions. The kernel checks permission, applies the deadline and
+  records the call.
+- **Approvals.** Kernel tools flagged as side-effecting, and `@tool(approval=True)`
+  functions, are held until the owner approves them, through `approve=` or in
+  AIOS Manager.
+- **Stable identity.** The agent ID comes from your UID and the agent name.
+  Only one agent with that name runs per user, and its storage survives
+  restarts.
+- **Tracing.** When the administrator enables tracing for the agent
+  (`sudo aiosctl trace enable <agent-id>`), runs appear in AIOS Trace with
+  kernel queue and lease timings. Tracing is off by default.
+- **Storage.** `agent.storage` is private, versioned and quota-limited.
+
+The SDK needs `aios.ko` loaded and `libaios.so` installed. There is no
+userspace fallback. Without the kernel, the SDK raises `KernelUnavailable`.
+
+## Requirements
+
+- Python 3.11 or later
+- `aios.ko` loaded, with the LLM worker running. Storage and kernel tools also
+  need the storage and tool workers.
+- Your user in the `aios` group
+- `libaios.so` in `/usr/lib`, or its path in `VECTROS_LIBAIOS`
+
+```sh
+pip install vectros-sdk
+```
+
+The package installs as `vectros-sdk` and imports as `vectros`. On Vectros OS
+it is preinstalled as the `python-vectros` package.
+
+## Agent
+
+```python
+Agent(
+    name,                 # shown in AIOS Manager and Trace
+    model=None,           # default: the LLM worker's model
+    tools=[],             # @tool functions and/or kernel tool names
+    system=None,          # system prompt
+    session=None,         # keep the conversation across runs and restarts
+    max_steps=10,         # maximum model calls per run
+    approve=None,         # approve(tool_name, args) -> bool
+    timeout=120,          # seconds per model or tool call
+    tool_protocol="native",  # or "json" for models without function calling
+)
+```
+
+| Call | Result |
+| --- | --- |
+| `agent.run(prompt)` | Final answer as `str` |
+| `agent.stream(prompt)` | `Event`s: `token`, `tool_call`, `tool_result`, `answer` |
+| `agent.storage.write(path, data)` / `.read(path)` | Kernel storage |
+| `agent.reset()` | Forget the session |
+| `agent.close()` or `with Agent(...)` | Unregister now, not at exit |
+
+```python
+for event in agent.stream("Plan my day"):
+    if event.kind == "token":
+        print(event.data, end="")
+```
+
+## Tools
+
+```python
+@tool
+def search(query: str, limit: int = 5) -> list[str]:
+    """Search the docs.
+
+    Args:
+        query: What to look for.
+    """
+
+@tool(approval=True)          # runs only if approve() returns True
+def send_email(to: str, body: str) -> str: ...
+
+agent = Agent("ops", tools=[search, send_email, "search_web"], approve=ask_terminal)
+```
+
+- The SDK builds the parameter schema from type hints, and descriptions from
+  the docstring and its `Args:` section.
+- A string names a tool registered in the kernel, for example an admin tool or
+  an MCP tool such as `github__create_issue`. These run in the AIOS tool worker.
+- `@tool` functions run in the agent's own process. Each call is first
+  submitted as a kernel client tool call (ABI 4.3). The function runs only
+  after the kernel hands the call back, which can be after owner approval.
+- When a tool raises an error, the error goes back to the model, and the model
+  can try again.
+- Tool calls use the model's native function calling. For models without
+  function calling, set `tool_protocol="json"`: the agent then asks for JSON
+  replies.
+
+## Sessions
+
+```python
+agent = Agent("support", session="customer-42")
+```
+
+History is stored in `$XDG_STATE_HOME/vectros/sessions/<agent>/<session>.json`
+and survives restarts. Only user prompts and final answers are kept, up to 40
+messages.
+
+## CLI
+
+```sh
+vectros init helper         # helper/vectros.toml + helper/agent.py
+cd helper
+vectros chat                # interactive; or: vectros chat "one question"
+vectros run                 # run the entry script
+vectros deploy me@host      # deploy to a Vectros OS host
+vectros logs -f             # follow the deployed agent's journal
+vectros status
+vectros stop
+```
+
+`vectros.toml`:
+
+```toml
+[agent]
+name = "helper"
+entry = "agent.py"     # script run by `vectros run` and by the service
+object = "agent"       # Agent variable used by `vectros chat`
+
+[deploy]
+host = "me@vectros-host"
+```
+
+`vectros deploy` does the following:
+
+1. Checks that the host has `/dev/aios` and the `vectros` package.
+2. Copies the project with rsync to `~/.local/share/vectros/agents/<name>`.
+3. Creates a venv with system site packages and installs `requirements.txt`
+   if the project has one.
+4. Starts the systemd user service `vectros-agent@<name>`, which runs
+   `python -m vectros run`.
+
+To keep the agent running after you log out, run `loginctl enable-linger` on
+the host.
+
+## Tests
+
+```sh
+pytest                         # unit tests, fake kernel
+VECTROS_E2E=1 pytest -m kernel # real aios.ko and workers
+```
+
+## Kernel versions
+
+The SDK needs ABI 4. Kernels before 4.3 still work with these limits:
+
+- Agent IDs are random, so `agent.storage` data is not readable after a restart.
+- `@tool` functions run in-process without kernel mediation. The SDK enforces
+  `approval=True` itself and denies the call when no `approve=` is set.
+
+## Limits
+
+- The kernel sees that a `@tool` function ran, but it cannot see what the
+  function does inside the agent process.
+- Sessions are local files on the host, not kernel storage. Kernel storage
+  files are limited to 64 KiB.
+- Native tool calls need the LLM worker that returns the tool envelope
+  (vectros-kernel with ABI 4.3). An older worker returns plain text, so the
+  agent treats the reply as the final answer.

vectros_sdk-2.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# The import package is `vectros`; the PyPI name "vectros" belongs to an
+# unrelated project.
+name = "vectros-sdk"
+version = "2.0.0"
+description = "Build AI agents that run on the AIOS kernel (Vectros OS)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "The Vectros authors" }]
+keywords = ["agents", "llm", "aios", "kernel", "vectros"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/vectros/vectros-sdk"
+Issues = "https://github.com/vectros/vectros-sdk/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+vectros = "vectros.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["vectros*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+markers = ["kernel: needs a loaded aios.ko, libaios.so and running workers"]

vectros_sdk-2.0.0/setup.cfg

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