autarkia 0.1.0__tar.gz

autarkia-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

autarkia-0.1.0/LICENSE

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

autarkia-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: autarkia
+Version: 0.1.0
+Summary: Tool governance for AI agents: registry, risk levels, role-based access, visibility rules, and execution guards. The tool layer of the Autarkia agent runtime.
+Project-URL: Homepage, https://qishihao.icu/projects/autarkia
+Project-URL: Repository, https://github.com/hakituo/autarkia-tools
+Project-URL: Autarkia Runtime, https://github.com/hakituo/Autarkia
+Project-URL: Author, https://qishihao.icu
+Author-email: Shihao Qi <qishihao512@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,autarkia,function-calling,llm,role-based-access,self-hosted,tool-governance,tool-registry,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# autarkia
+
+**Tool governance for AI agents** — a registry, risk levels, role-based access, visibility rules, and execution guards for LLM tool calling.
+
+This is the tool layer of [Autarkia](https://qishihao.icu/projects/autarkia), a self-hosted agent runtime that has run on a single machine for months: around 90 tools across 20+ domains, isolated per role, with pre-execution permission checks — not prompt promises.
+
+## Why
+
+Most agent frameworks answer "how do I call a tool". This library answers the question that shows up after your agent has been running for a while: **who is allowed to call what, and what happens before it runs.**
+
+- **Registry** — one place for tool instances, runtime enable/disable, and stable OpenAI function-calling schemas (byte-stable output so API-side prompt caches keep hitting).
+- **Declared risk levels** — every tool carries an explicit risk class (`read`, `write`, `external_write`, `device_read`, `device_control`, `sensitive`). If you forgot to declare one, it simply does not appear in discovery. Risk is never inferred.
+- **Role policies** — resident / on-demand / disabled per role, plus keyword routing for the first turn. A role that was never granted a tool cannot see it, search for it, or call it.
+- **Visibility rules** — persona-level allow/deny by name or category, with mode and sensitive-mode overlays.
+- **Execution guard** — authorization against the request's own snapshot, argument validation, and per-call context isolation (no shared mutable tool state across concurrent roles).
+
+Zero runtime dependencies beyond `pydantic`. No framework lock-in: tools are plain classes, the registry is a plain object, and the OpenAI-compatible schema export works with any API that speaks function calling.
+
+## Install
+
+```bash
+pip install autarkia
+```
+
+## Quick start
+
+```python
+from pydantic import BaseModel
+
+from autarkia.tools import BaseTool, ToolCatalog, ToolDeclaration, ToolRegistry
+
+
+class EchoArgs(BaseModel):
+    text: str
+
+class EchoTool(BaseTool):
+    name = "echo"
+    description = "Echo the given text back."
+    args_schema = EchoArgs
+
+    async def _run(self, text: str) -> str:
+        return text
+
+
+# Declare what each tool is allowed to be. Undeclared tools stay invisible.
+catalog = ToolCatalog()
+catalog.declare(
+    "echo",
+    ToolDeclaration(
+        domain="utility",
+        risk_level="read",
+        load_policy="base",
+        tags=("demo", "echo"),
+    ),
+)
+
+registry = ToolRegistry(catalog=catalog)
+registry.register(EchoTool())
+
+# OpenAI function-calling format, cached and byte-stable.
+print(registry.get_openai_tools())
+```
+
+### Role-based access
+
+```python
+from autarkia.tools import RolePolicyResolver
+
+profiles = {
+    "defaults": {"on_demand": ["domain:*"]},
+    "roles": {
+        "librarian": {"resident": ["echo"], "disabled": ["domain:execution"]},
+    },
+    "modes": {},
+    "routes": [
+        {"keywords": ["repeat"], "tools": ["echo"]},
+    ],
+}
+
+resolver = RolePolicyResolver(profiles, catalog=catalog)
+policy = resolver.resolve(scope="librarian")
+policy.allows("echo")        # True
+policy.allows("run_code")    # False — disabled for this role
+
+picked = resolver.select("please repeat this", scope="librarian")
+```
+
+### Execution guard
+
+```python
+import asyncio
+from autarkia.tools import execute_tool_call
+
+result = asyncio.run(execute_tool_call(
+    agent=agent,                 # any object exposing .tool_registry
+    tool_name="echo",
+    arguments={"text": "hi"},
+    user_id="user-1",
+    allowed_tool_names=policy.visible_tool_names(),
+))
+```
+
+The guard never trusts the model: it checks the tool against the allowed list passed by the orchestrator, validates arguments, and copies the tool instance so concurrent roles cannot bleed state into each other.
+
+## Concepts
+
+| Piece | File | What it decides |
+| --- | --- | --- |
+| `BaseTool` | `autarkia.tools.base` | what a tool is (name, args schema, category) |
+| `ToolCatalog` / `ToolDeclaration` | `autarkia.tools.metadata` | domain, tags, risk level, load policy — declared per tool |
+| `ToolRegistry` | `autarkia.tools.registry` | registration, enable/disable, schema export, discovery search |
+| `RoleToolPolicy` / `RolePolicyResolver` | `autarkia.tools.policy` | resident / on-demand / disabled per role, keyword routing |
+| `filter_tool_names` | `autarkia.tools.visibility` | persona allow/deny, mode and sensitive-mode overlays |
+| `execute_tool_call` | `autarkia.tools.execution` | the last line of defense before a tool runs |
+
+Risk levels: `read` → `write` → `external_write` → `device_read` → `device_control` → `sensitive`.
+Load policies: `base` (always offered), `on_demand` (found through discovery), `hidden` (exists, never advertised).
+
+## The bigger picture
+
+Autarkia itself is not on PyPI — it is a single-machine runtime, not a SaaS. This package ships the governance layer that survived that experiment, because it turned out to be the part other projects kept asking for.
+
+- Project page: <https://qishihao.icu/projects/autarkia>
+- Runtime repository: <https://github.com/hakituo/Autarkia>
+- This package: <https://github.com/hakituo/autarkia-tools>
+- Author: Shihao Qi — <https://qishihao.icu>
+
+## License
+
+MIT

autarkia-0.1.0/README.md

@@ -0,0 +1,130 @@
+# autarkia
+
+**Tool governance for AI agents** — a registry, risk levels, role-based access, visibility rules, and execution guards for LLM tool calling.
+
+This is the tool layer of [Autarkia](https://qishihao.icu/projects/autarkia), a self-hosted agent runtime that has run on a single machine for months: around 90 tools across 20+ domains, isolated per role, with pre-execution permission checks — not prompt promises.
+
+## Why
+
+Most agent frameworks answer "how do I call a tool". This library answers the question that shows up after your agent has been running for a while: **who is allowed to call what, and what happens before it runs.**
+
+- **Registry** — one place for tool instances, runtime enable/disable, and stable OpenAI function-calling schemas (byte-stable output so API-side prompt caches keep hitting).
+- **Declared risk levels** — every tool carries an explicit risk class (`read`, `write`, `external_write`, `device_read`, `device_control`, `sensitive`). If you forgot to declare one, it simply does not appear in discovery. Risk is never inferred.
+- **Role policies** — resident / on-demand / disabled per role, plus keyword routing for the first turn. A role that was never granted a tool cannot see it, search for it, or call it.
+- **Visibility rules** — persona-level allow/deny by name or category, with mode and sensitive-mode overlays.
+- **Execution guard** — authorization against the request's own snapshot, argument validation, and per-call context isolation (no shared mutable tool state across concurrent roles).
+
+Zero runtime dependencies beyond `pydantic`. No framework lock-in: tools are plain classes, the registry is a plain object, and the OpenAI-compatible schema export works with any API that speaks function calling.
+
+## Install
+
+```bash
+pip install autarkia
+```
+
+## Quick start
+
+```python
+from pydantic import BaseModel
+
+from autarkia.tools import BaseTool, ToolCatalog, ToolDeclaration, ToolRegistry
+
+
+class EchoArgs(BaseModel):
+    text: str
+
+class EchoTool(BaseTool):
+    name = "echo"
+    description = "Echo the given text back."
+    args_schema = EchoArgs
+
+    async def _run(self, text: str) -> str:
+        return text
+
+
+# Declare what each tool is allowed to be. Undeclared tools stay invisible.
+catalog = ToolCatalog()
+catalog.declare(
+    "echo",
+    ToolDeclaration(
+        domain="utility",
+        risk_level="read",
+        load_policy="base",
+        tags=("demo", "echo"),
+    ),
+)
+
+registry = ToolRegistry(catalog=catalog)
+registry.register(EchoTool())
+
+# OpenAI function-calling format, cached and byte-stable.
+print(registry.get_openai_tools())
+```
+
+### Role-based access
+
+```python
+from autarkia.tools import RolePolicyResolver
+
+profiles = {
+    "defaults": {"on_demand": ["domain:*"]},
+    "roles": {
+        "librarian": {"resident": ["echo"], "disabled": ["domain:execution"]},
+    },
+    "modes": {},
+    "routes": [
+        {"keywords": ["repeat"], "tools": ["echo"]},
+    ],
+}
+
+resolver = RolePolicyResolver(profiles, catalog=catalog)
+policy = resolver.resolve(scope="librarian")
+policy.allows("echo")        # True
+policy.allows("run_code")    # False — disabled for this role
+
+picked = resolver.select("please repeat this", scope="librarian")
+```
+
+### Execution guard
+
+```python
+import asyncio
+from autarkia.tools import execute_tool_call
+
+result = asyncio.run(execute_tool_call(
+    agent=agent,                 # any object exposing .tool_registry
+    tool_name="echo",
+    arguments={"text": "hi"},
+    user_id="user-1",
+    allowed_tool_names=policy.visible_tool_names(),
+))
+```
+
+The guard never trusts the model: it checks the tool against the allowed list passed by the orchestrator, validates arguments, and copies the tool instance so concurrent roles cannot bleed state into each other.
+
+## Concepts
+
+| Piece | File | What it decides |
+| --- | --- | --- |
+| `BaseTool` | `autarkia.tools.base` | what a tool is (name, args schema, category) |
+| `ToolCatalog` / `ToolDeclaration` | `autarkia.tools.metadata` | domain, tags, risk level, load policy — declared per tool |
+| `ToolRegistry` | `autarkia.tools.registry` | registration, enable/disable, schema export, discovery search |
+| `RoleToolPolicy` / `RolePolicyResolver` | `autarkia.tools.policy` | resident / on-demand / disabled per role, keyword routing |
+| `filter_tool_names` | `autarkia.tools.visibility` | persona allow/deny, mode and sensitive-mode overlays |
+| `execute_tool_call` | `autarkia.tools.execution` | the last line of defense before a tool runs |
+
+Risk levels: `read` → `write` → `external_write` → `device_read` → `device_control` → `sensitive`.
+Load policies: `base` (always offered), `on_demand` (found through discovery), `hidden` (exists, never advertised).
+
+## The bigger picture
+
+Autarkia itself is not on PyPI — it is a single-machine runtime, not a SaaS. This package ships the governance layer that survived that experiment, because it turned out to be the part other projects kept asking for.
+
+- Project page: <https://qishihao.icu/projects/autarkia>
+- Runtime repository: <https://github.com/hakituo/Autarkia>
+- This package: <https://github.com/hakituo/autarkia-tools>
+- Author: Shihao Qi — <https://qishihao.icu>
+
+## License
+
+MIT

autarkia-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "autarkia"
+version = "0.1.0"
+description = "Tool governance for AI agents: registry, risk levels, role-based access, visibility rules, and execution guards. The tool layer of the Autarkia agent runtime."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Shihao Qi", email = "qishihao512@gmail.com" },
+]
+keywords = [
+    "agent",
+    "tools",
+    "tool-registry",
+    "tool-governance",
+    "llm",
+    "function-calling",
+    "role-based-access",
+    "autarkia",
+    "self-hosted",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://qishihao.icu/projects/autarkia"
+Repository = "https://github.com/hakituo/autarkia-tools"
+"Autarkia Runtime" = "https://github.com/hakituo/Autarkia"
+Author = "https://qishihao.icu"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/autarkia"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE"]

autarkia-0.1.0/src/autarkia/__init__.py

@@ -0,0 +1,35 @@
+"""Autarkia — tool governance for AI agents.
+
+Registry, risk levels, role-based access, visibility rules, and execution
+guards for LLM tool calling. The tool layer of the Autarkia agent runtime.
+"""
+
+__version__ = "0.1.0"
+
+from autarkia.tools import (
+    BaseTool,
+    RolePolicyResolver,
+    RoleToolPolicy,
+    ToolCatalog,
+    ToolDeclaration,
+    ToolDiscoveryMetadata,
+    ToolRegistry,
+    ToolVisibilityContext,
+    ToolVisibilityRules,
+    execute_tool_call,
+    filter_tool_names,
+)
+
+__all__ = [
+    "BaseTool",
+    "RolePolicyResolver",
+    "RoleToolPolicy",
+    "ToolCatalog",
+    "ToolDeclaration",
+    "ToolDiscoveryMetadata",
+    "ToolRegistry",
+    "ToolVisibilityContext",
+    "ToolVisibilityRules",
+    "execute_tool_call",
+    "filter_tool_names",
+]

autarkia-0.1.0/src/autarkia/tools/__init__.py

@@ -0,0 +1,32 @@
+"""Tool governance: registry, declared risk levels, role policies, visibility, execution guard."""
+
+from autarkia.tools.base import BaseTool
+from autarkia.tools.execution import execute_tool_call
+from autarkia.tools.metadata import (
+    ToolCatalog,
+    ToolDeclaration,
+    ToolDiscoveryMetadata,
+    search_tool_metadata,
+)
+from autarkia.tools.policy import RolePolicyResolver, RoleToolPolicy
+from autarkia.tools.registry import ToolRegistry
+from autarkia.tools.visibility import (
+    ToolVisibilityContext,
+    ToolVisibilityRules,
+    filter_tool_names,
+)
+
+__all__ = [
+    "BaseTool",
+    "RolePolicyResolver",
+    "RoleToolPolicy",
+    "ToolCatalog",
+    "ToolDeclaration",
+    "ToolDiscoveryMetadata",
+    "ToolRegistry",
+    "ToolVisibilityContext",
+    "ToolVisibilityRules",
+    "execute_tool_call",
+    "filter_tool_names",
+    "search_tool_metadata",
+]

autarkia-0.1.0/src/autarkia/tools/base.py

@@ -0,0 +1,86 @@
+"""BaseTool — what a tool is.
+
+Ported from the Autarkia runtime's tool base class. Host-specific helpers
+(QQ master detection, persona scope resolution) were replaced with
+runtime-context conventions so the base class stays dependency-free.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Type
+
+from pydantic import BaseModel
+
+
+class BaseTool(ABC):
+    """Base class for all tools.
+
+    Class attributes:
+        name: unique tool name (used as the registry key).
+        description: full description, also used as the function-calling
+            description in exported schemas.
+        args_schema: optional pydantic model describing the arguments.
+        short_description: one-line hint for prompt injection; overrides
+            ``description`` when a compact list is rendered.
+        category: free-form grouping label (e.g. "memory", "device").
+        enabled_by_default: whether the tool is offered before any
+            explicit enable/disable call.
+    """
+
+    name: str
+    description: str
+    args_schema: Optional[Type[BaseModel]] = None
+    short_description: Optional[str] = None
+    category: str = "utility"
+    enabled_by_default: bool = True
+
+    def set_runtime_context(self, context: Dict[str, Any]) -> None:
+        """Inject runtime context (agent, user_id, scope, ...) before execution."""
+        self._runtime_context = context
+
+    def _get_ctx(self, key: str, default: Any = None) -> Any:
+        """Convenience accessor for runtime context keys."""
+        return getattr(self, "_runtime_context", {}).get(key, default)
+
+    def is_master(self) -> bool:
+        """Whether the current session belongs to a master/admin caller.
+
+        The orchestrator decides what "master" means and injects either
+        ``is_master: bool`` or ``master_ids: collection[str]`` alongside
+        ``user_id`` into the runtime context.
+        """
+        if bool(self._get_ctx("is_master", False)):
+            return True
+        master_ids = self._get_ctx("master_ids")
+        if not master_ids:
+            return False
+        user_id = str(self._get_ctx("user_id") or "").strip()
+        return bool(user_id) and user_id in {str(item) for item in master_ids}
+
+    def current_scope(self) -> str:
+        """Scope of the current call (role / persona slug / tenant id).
+
+        Resolution order, all injected per request by the orchestrator:
+        ``scope`` → ``persona_filename`` → empty string. Never reads
+        global singletons, so concurrent roles stay isolated.
+        """
+        scope = str(self._get_ctx("scope") or "").strip()
+        if scope:
+            return scope
+        return str(self._get_ctx("persona_filename") or "").strip()
+
+    @abstractmethod
+    async def _run(self, *args, **kwargs) -> Any:
+        """Implementation of the tool."""
+
+    async def run(self, *args, **kwargs) -> str:
+        """Execute the tool and return the result as a string.
+
+        Tool-internal exceptions are converted into an error string on
+        purpose: the model reads the result either way, and a weather API
+        timeout should look like a retryable outcome, not a crash.
+        """
+        try:
+            result = await self._run(*args, **kwargs)
+            return str(result)
+        except Exception as exc:  # noqa: BLE001 - deliberate boundary
+            return f"Error executing tool {self.name}: {exc}"

autarkia-0.1.0/src/autarkia/tools/execution.py

@@ -0,0 +1,61 @@
+"""Unified execution boundary: authorization snapshot + per-call isolation.
+
+Ported from the Autarkia runtime unchanged in behavior — it is already
+host-free. This is the last line of defense before a tool runs.
+"""
+
+from copy import copy
+import json
+from typing import Any, List, Mapping, Optional
+
+
+async def execute_tool_call(
+    *,
+    agent: Any,
+    tool_name: str,
+    arguments: Mapping[str, Any],
+    user_id: str,
+    allowed_tool_names: List[str],
+    persona_filename: Optional[str] = None,
+    is_sensitive_mode: bool = False,
+    used_tool_names: Optional[List[str]] = None,
+    last_user_text: str = "",
+) -> str:
+    """Execute one tool call against the request's own authorization snapshot.
+
+    The model never picks roles, paths, or permissions here — everything
+    comes from the orchestrator's snapshot for this request.
+
+    ``used_tool_names`` collects what was authorized *and* actually
+    dispatched (not what succeeded — ``BaseTool.run()`` turns tool errors
+    into strings by design, and a timed-out weather call is exactly the
+    thing the next turn should be allowed to retry).
+
+    ``last_user_text`` carries the raw user message for tools that must
+    only reference what the user actually said.
+    """
+    registry = getattr(agent, "tool_registry", None)
+    if tool_name not in allowed_tool_names or registry is None or not registry.is_enabled(tool_name):
+        return json.dumps(
+            {"ok": False, "error": "tool not allowed for the current role", "tool": tool_name},
+            ensure_ascii=False,
+        )
+    if not isinstance(arguments, Mapping):
+        return json.dumps(
+            {"ok": False, "error": "tool arguments must be an object", "tool": tool_name},
+            ensure_ascii=False,
+        )
+    # The registry stores reusable implementations; every call gets an
+    # isolated copy so concurrent roles cannot bleed state into each other.
+    tool = copy(registry.get_tool(tool_name))
+    tool.set_runtime_context({
+        "agent": agent,
+        "user_id": user_id,
+        "persona_filename": persona_filename,
+        "scope": "sensitive" if is_sensitive_mode else "sfw",
+        "allowed_tool_names": list(allowed_tool_names),
+        "last_user_text": str(last_user_text or ""),
+    })
+    if used_tool_names is not None and tool_name not in used_tool_names:
+        used_tool_names.append(tool_name)
+    return await tool.run(**dict(arguments))