Skip to main content

PyPI downloads Swarmauri

Monthly downloads Repository hits Supported Python versions License Release version

Swarmauri Tool Scroll File

swarmauri_tool_scrollfile gives agents and workflows a bounded way to inspect large UTF-8 text files. It returns numbered lines together with stable previous and next page positions, avoiding full-file output.

Features

  • Restricts reads to service-configured filesystem roots by default.
  • Rejects symlinks unless the service owner explicitly opts in.
  • Caps page size, scanned lines and bytes, individual-line size, elapsed time, and returned bytes.
  • Navigates up or down using one-based line anchors.
  • Returns line numbers and explicit previous/next page positions.
  • Clamps an anchor beyond EOF to the final available page.
  • Validates paths and navigation arguments before reading.
  • Registers as a swarmauri.tools entry point.
  • Supports Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Installation

uv add swarmauri_tool_scrollfile
pip install swarmauri_tool_scrollfile

Usage

from pathlib import Path

from swarmauri_tool_scrollfile import ScrollFileTool

tool = ScrollFileTool(allowed_roots=[str(Path("logs").resolve())])
first_page = tool("logs/application.log")

if first_page["has_next"]:
    second_page = tool(
        "logs/application.log",
        start_line=first_page["next_start_line"],
        page_size=first_page["page_size"],
        direction="down",
    )

An upward request treats start_line as the current page anchor and returns the preceding page:

previous_page = tool(
    "logs/application.log",
    start_line=second_page["start_line"],
    page_size=second_page["page_size"],
    direction="up",
)

Each result contains lines, start_line, end_line, page_size, has_previous, has_next, previous_start_line, and next_start_line.

Security and Resource Limits

file_path is agent-controlled, but filesystem policy is not. The service owner configures allowed_roots when creating the tool; requested paths are canonically resolved and must remain inside one of those roots. Paths containing symlinks are rejected by default, and the resolved target must be a regular file.

tool = ScrollFileTool(
    allowed_roots=["/srv/application-logs", "/srv/reports"],
)

The default root is the process working directory. Set allow_symlinks=True only when following symlinks is part of the trusted service configuration. allow_unrestricted_paths=True is a privileged opt-in that disables root containment; use it only when the process already runs in a least-privilege filesystem sandbox.

Each call enforces service-owned limits: at most 100 returned lines, 100,000 scanned lines, 8 MiB scanned data, 64 KiB per line, 256 KiB returned content, and two seconds of file-reading time. Exceeding a limit raises ValueError rather than returning a partial or ambiguous page.

Workflow Integration

from swarmauri_standard.tools.ToolCollection import ToolCollection
from swarmauri_tool_scrollfile import ScrollFileTool

tools = ToolCollection(
    tools=[ScrollFileTool(allowed_roots=["/srv/application-logs"])]
)

Performance

The tool streams from the start of the file to the requested page and holds at most one page plus one lookahead line in memory, subject to the limits above. Memory use is O(page_size); runtime is O(start_line + page_size) for a stateless request.

License

This package is licensed under Apache-2.0.

Descriptor-based opening and page boundaries

Where Linux openat2 is available, lookups use beneath-root resolution. If the syscall is unavailable, the POSIX fallback opens a single child of the trusted root with a no-follow lookup. Nested file lookups fail with ENOTSUP. Policy denials such as EPERM or EACCES are returned as errors, including when opening the configured root.

The service must control the configured root, its ancestors, and mount configuration. A root handle identifies the directory opened by the tool. Filesystem permissions still govern concurrent changes to opened objects.

allow_symlinks=True requires Linux openat2 and permits only relative links whose complete resolution stays beneath the selected root. Absolute links, root escapes, and magic links are rejected. This intentionally narrows the old opt-in. allow_unrestricted_paths=True anchors at the filesystem root; it does not independently enable symlink following. Configured root paths cannot contain symlinks or parent traversal.

Opened handles retain inode identity if directories are renamed. This prevents symlink substitution from redirecting a read, but does not freeze file contents or prevent another actor from moving an opened directory. Services must control permissions on their trees.

The returned-content budget applies to the page actually returned, including EOF fallback. The preceding rolling buffer is bounded separately by page size and individual-line limits; large earlier lines no longer reject a small later page merely because they exceed the return budget. A one-byte lookahead detects the next page without decoding or line-validating its contents. That probe is still charged against scanned-line and scanned-byte limits. Time checks remain cooperative and cannot interrupt a filesystem syscall already blocked in the kernel.

Windows filesystem support

On Windows the backend opens the local drive by its volume identity and opens each component relative to a held directory handle. It rejects junctions and other reparse points and does not accept UNC or device paths, alternate data streams, or ambiguous trailing dots or spaces, or reserved DOS basenames. Ancestors are opened for traversal without requiring listing access. Volume and directory handles deny delete sharing during traversal. Returned paths are descriptive snapshots. Confined reads check the opened file and reject files with multiple hard links. Filesystem permissions govern concurrent changes to file contents.

Metadata

Release files for swarmauri_tool_scrollfile 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for swarmauri_tool_scrollfile 0.1.0
File Size Uploaded Provenance Actions
swarmauri_tool_scrollfile-0.1.0.tar.gz 17.4 kB Without provenance Details for swarmauri_tool_scrollfile-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for swarmauri_tool_scrollfile 0.1.0
File Interpreter ABI Platform Actions
swarmauri_tool_scrollfile-0.1.0-py3-none-any.whl Python 3 none any Details for swarmauri_tool_scrollfile-0.1.0-py3-none-any.whl

Total release size: 35.1 kB

Release files / swarmauri_tool_scrollfile-0.1.0.tar.gz

Download URL swarmauri_tool_scrollfile-0.1.0.tar.gz
Size 17.4 kB
Tags Source
SHA-256 checksum
How to use checksums
4839659b5d8b145ef2090ffe2637f100dff083dde9ee4a29a0a9ad709969c553
BLAKE2b-256 checksum
How to use checksums
09655133bb5219f6d26f3d98dc839713e253d524dd3ab6e66ba52d83241abd23
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / swarmauri_tool_scrollfile-0.1.0-py3-none-any.whl

Download URL swarmauri_tool_scrollfile-0.1.0-py3-none-any.whl
Size 17.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0f1bd54aedfb5571f18c476c9bbe47105892c6200c6defa5ae084f05982a1300
BLAKE2b-256 checksum
How to use checksums
da5691aca58d1d3e67f21f7a362cbb997c8328d92f68f063d78a0a5559288fcc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for swarmauri_tool_scrollfile 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page