agentfs-sdk 0.4.0rc5__tar.gz

agentfs_sdk-0.4.0rc5/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+recursive-include agentfs_sdk *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

agentfs_sdk-0.4.0rc5/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: agentfs-sdk
+Version: 0.4.0rc5
+Summary: AgentFS Python SDK - A filesystem and key-value store for AI agents
+Author: Turso
+License: MIT
+Project-URL: Homepage, https://github.com/tursodatabase/agentfs
+Project-URL: Source, https://github.com/tursodatabase/agentfs
+Project-URL: Repository, https://github.com/tursodatabase/agentfs
+Project-URL: Issues, https://github.com/tursodatabase/agentfs/issues
+Keywords: ai,agent,turso,sqlite,key-value,filesystem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyturso==0.4.0rc17
+
+# AgentFS Python SDK
+
+A filesystem and key-value store for AI agents, powered by SQLite and [pyturso](https://pypi.org/project/pyturso/).
+
+## Installation
+
+```bash
+pip install agentfs-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from agentfs_sdk import AgentFS, AgentFSOptions
+
+async def main():
+    # Open an agent filesystem
+    agent = await AgentFS.open(AgentFSOptions(id='my-agent'))
+
+    # Use key-value store
+    await agent.kv.set('config', {'debug': True, 'version': '1.0'})
+    config = await agent.kv.get('config')
+    print(f"Config: {config}")
+
+    # Use filesystem
+    await agent.fs.write_file('/data/notes.txt', 'Hello, AgentFS!')
+    content = await agent.fs.read_file('/data/notes.txt')
+    print(f"Content: {content}")
+
+    # Track tool calls
+    call_id = await agent.tools.start('search', {'query': 'Python'})
+    await agent.tools.success(call_id, {'results': ['result1', 'result2']})
+
+    # Get statistics
+    stats = await agent.tools.get_stats()
+    for stat in stats:
+        print(f"{stat.name}: {stat.total_calls} calls, {stat.avg_duration_ms:.2f}ms avg")
+
+    # Close the database
+    await agent.close()
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+## Features
+
+### Key-Value Store
+
+Simple key-value storage with JSON serialization:
+
+```python
+# Set a value
+await agent.kv.set('user:123', {'name': 'Alice', 'age': 30})
+
+# Get a value
+user = await agent.kv.get('user:123')
+
+# List by prefix
+users = await agent.kv.list('user:')
+
+# Delete a value
+await agent.kv.delete('user:123')
+```
+
+### Filesystem
+
+POSIX-like filesystem operations:
+
+```python
+# Write a file (creates parent directories automatically)
+await agent.fs.write_file('/data/config.json', '{"key": "value"}')
+
+# Read a file
+content = await agent.fs.read_file('/data/config.json')
+
+# Read as bytes
+data = await agent.fs.read_file('/data/image.png', encoding=None)
+
+# List directory
+entries = await agent.fs.readdir('/data')
+
+# Get file stats
+stats = await agent.fs.stat('/data/config.json')
+print(f"Size: {stats.size} bytes")
+print(f"Modified: {stats.mtime}")
+print(f"Is file: {stats.is_file()}")
+
+# Delete a file
+await agent.fs.delete_file('/data/config.json')
+```
+
+### Tool Calls Tracking
+
+Track and analyze tool/function calls:
+
+```python
+# Start a tool call
+call_id = await agent.tools.start('search', {'query': 'Python'})
+
+# Mark as successful
+await agent.tools.success(call_id, {'results': [...]})
+
+# Or mark as failed
+await agent.tools.error(call_id, 'Connection timeout')
+
+# Record a completed call
+await agent.tools.record(
+    'search',
+    started_at=1234567890,
+    completed_at=1234567892,
+    parameters={'query': 'Python'},
+    result={'results': [...]}
+)
+
+# Query tool calls
+calls = await agent.tools.get_by_name('search', limit=10)
+recent = await agent.tools.get_recent(since=1234567890)
+
+# Get statistics
+stats = await agent.tools.get_stats()
+for stat in stats:
+    print(f"{stat.name}: {stat.successful}/{stat.total_calls} successful")
+```
+
+## Configuration
+
+### Using Agent ID
+
+Creates a database at `.agentfs/{id}.db`:
+
+```python
+agent = await AgentFS.open(AgentFSOptions(id='my-agent'))
+```
+
+### Using Custom Path
+
+Specify a custom database path:
+
+```python
+agent = await AgentFS.open(AgentFSOptions(path='./data/mydb.db'))
+```
+
+### Using Both
+
+You can specify both for clarity:
+
+```python
+agent = await AgentFS.open(AgentFSOptions(id='my-agent', path='./data/mydb.db'))
+```
+
+## Context Manager Support
+
+Use AgentFS with async context managers:
+
+```python
+async with await AgentFS.open(AgentFSOptions(id='my-agent')) as agent:
+    await agent.kv.set('key', 'value')
+    # Database is automatically closed when exiting the context
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+uv sync --group dev
+
+# Run tests
+uv run pytest
+
+# Format code
+uv run ruff format agentfs_sdk tests
+
+# Check code
+uv run ruff check agentfs_sdk tests
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Links
+
+- [GitHub Repository](https://github.com/tursodatabase/agentfs)
+- [TypeScript SDK](https://github.com/tursodatabase/agentfs/tree/main/sdk/typescript)
+- [tursodb](https://github.com/tursodatabase/turso)
+- [pyturso](https://pypi.org/project/pyturso/)

agentfs_sdk-0.4.0rc5/README.md

@@ -0,0 +1,190 @@
+# AgentFS Python SDK
+
+A filesystem and key-value store for AI agents, powered by SQLite and [pyturso](https://pypi.org/project/pyturso/).
+
+## Installation
+
+```bash
+pip install agentfs-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from agentfs_sdk import AgentFS, AgentFSOptions
+
+async def main():
+    # Open an agent filesystem
+    agent = await AgentFS.open(AgentFSOptions(id='my-agent'))
+
+    # Use key-value store
+    await agent.kv.set('config', {'debug': True, 'version': '1.0'})
+    config = await agent.kv.get('config')
+    print(f"Config: {config}")
+
+    # Use filesystem
+    await agent.fs.write_file('/data/notes.txt', 'Hello, AgentFS!')
+    content = await agent.fs.read_file('/data/notes.txt')
+    print(f"Content: {content}")
+
+    # Track tool calls
+    call_id = await agent.tools.start('search', {'query': 'Python'})
+    await agent.tools.success(call_id, {'results': ['result1', 'result2']})
+
+    # Get statistics
+    stats = await agent.tools.get_stats()
+    for stat in stats:
+        print(f"{stat.name}: {stat.total_calls} calls, {stat.avg_duration_ms:.2f}ms avg")
+
+    # Close the database
+    await agent.close()
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+## Features
+
+### Key-Value Store
+
+Simple key-value storage with JSON serialization:
+
+```python
+# Set a value
+await agent.kv.set('user:123', {'name': 'Alice', 'age': 30})
+
+# Get a value
+user = await agent.kv.get('user:123')
+
+# List by prefix
+users = await agent.kv.list('user:')
+
+# Delete a value
+await agent.kv.delete('user:123')
+```
+
+### Filesystem
+
+POSIX-like filesystem operations:
+
+```python
+# Write a file (creates parent directories automatically)
+await agent.fs.write_file('/data/config.json', '{"key": "value"}')
+
+# Read a file
+content = await agent.fs.read_file('/data/config.json')
+
+# Read as bytes
+data = await agent.fs.read_file('/data/image.png', encoding=None)
+
+# List directory
+entries = await agent.fs.readdir('/data')
+
+# Get file stats
+stats = await agent.fs.stat('/data/config.json')
+print(f"Size: {stats.size} bytes")
+print(f"Modified: {stats.mtime}")
+print(f"Is file: {stats.is_file()}")
+
+# Delete a file
+await agent.fs.delete_file('/data/config.json')
+```
+
+### Tool Calls Tracking
+
+Track and analyze tool/function calls:
+
+```python
+# Start a tool call
+call_id = await agent.tools.start('search', {'query': 'Python'})
+
+# Mark as successful
+await agent.tools.success(call_id, {'results': [...]})
+
+# Or mark as failed
+await agent.tools.error(call_id, 'Connection timeout')
+
+# Record a completed call
+await agent.tools.record(
+    'search',
+    started_at=1234567890,
+    completed_at=1234567892,
+    parameters={'query': 'Python'},
+    result={'results': [...]}
+)
+
+# Query tool calls
+calls = await agent.tools.get_by_name('search', limit=10)
+recent = await agent.tools.get_recent(since=1234567890)
+
+# Get statistics
+stats = await agent.tools.get_stats()
+for stat in stats:
+    print(f"{stat.name}: {stat.successful}/{stat.total_calls} successful")
+```
+
+## Configuration
+
+### Using Agent ID
+
+Creates a database at `.agentfs/{id}.db`:
+
+```python
+agent = await AgentFS.open(AgentFSOptions(id='my-agent'))
+```
+
+### Using Custom Path
+
+Specify a custom database path:
+
+```python
+agent = await AgentFS.open(AgentFSOptions(path='./data/mydb.db'))
+```
+
+### Using Both
+
+You can specify both for clarity:
+
+```python
+agent = await AgentFS.open(AgentFSOptions(id='my-agent', path='./data/mydb.db'))
+```
+
+## Context Manager Support
+
+Use AgentFS with async context managers:
+
+```python
+async with await AgentFS.open(AgentFSOptions(id='my-agent')) as agent:
+    await agent.kv.set('key', 'value')
+    # Database is automatically closed when exiting the context
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+uv sync --group dev
+
+# Run tests
+uv run pytest
+
+# Format code
+uv run ruff format agentfs_sdk tests
+
+# Check code
+uv run ruff check agentfs_sdk tests
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Links
+
+- [GitHub Repository](https://github.com/tursodatabase/agentfs)
+- [TypeScript SDK](https://github.com/tursodatabase/agentfs/tree/main/sdk/typescript)
+- [tursodb](https://github.com/tursodatabase/turso)
+- [pyturso](https://pypi.org/project/pyturso/)

agentfs_sdk-0.4.0rc5/agentfs_sdk/__init__.py

@@ -0,0 +1,22 @@
+"""AgentFS Python SDK
+
+A filesystem and key-value store for AI agents, powered by SQLite.
+"""
+
+from .agentfs import AgentFS, AgentFSOptions
+from .filesystem import Filesystem, Stats
+from .kvstore import KvStore
+from .toolcalls import ToolCall, ToolCalls, ToolCallStats
+
+__version__ = "0.4.0-pre.5"
+
+__all__ = [
+    "AgentFS",
+    "AgentFSOptions",
+    "KvStore",
+    "Filesystem",
+    "Stats",
+    "ToolCalls",
+    "ToolCall",
+    "ToolCallStats",
+]

agentfs_sdk-0.4.0rc5/agentfs_sdk/agentfs.py

@@ -0,0 +1,126 @@
+"""Main AgentFS class"""
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from turso.aio import Connection, connect
+
+from .filesystem import Filesystem
+from .kvstore import KvStore
+from .toolcalls import ToolCalls
+
+
+@dataclass
+class AgentFSOptions:
+    """Configuration options for opening an AgentFS instance
+
+    Attributes:
+        id: Unique identifier for the agent.
+            - If provided without `path`: Creates storage at `.agentfs/{id}.db`
+            - If provided with `path`: Uses the specified path
+        path: Explicit path to the database file.
+            - If provided: Uses the specified path directly
+            - Can be combined with `id`
+    """
+
+    id: Optional[str] = None
+    path: Optional[str] = None
+
+
+class AgentFS:
+    """AgentFS - A filesystem and key-value store for AI agents
+
+    Provides a unified interface for persistent storage using SQLite,
+    with support for key-value storage, filesystem operations, and
+    tool call tracking.
+    """
+
+    def __init__(self, db: Connection, kv: KvStore, fs: Filesystem, tools: ToolCalls):
+        """Private constructor - use AgentFS.open() instead"""
+        self._db = db
+        self.kv = kv
+        self.fs = fs
+        self.tools = tools
+
+    @staticmethod
+    async def open(options: AgentFSOptions) -> "AgentFS":
+        """Open an agent filesystem
+
+        Args:
+            options: Configuration options (id and/or path required)
+
+        Returns:
+            Fully initialized AgentFS instance
+
+        Raises:
+            ValueError: If neither id nor path is provided, or if id contains invalid characters
+
+        Example:
+            >>> # Using id (creates .agentfs/my-agent.db)
+            >>> agent = await AgentFS.open(AgentFSOptions(id='my-agent'))
+            >>>
+            >>> # Using id with custom path
+            >>> agent = await AgentFS.open(AgentFSOptions(id='my-agent', path='./data/mydb.db'))
+            >>>
+            >>> # Using path only
+            >>> agent = await AgentFS.open(AgentFSOptions(path='./data/mydb.db'))
+        """
+        # Require at least id or path
+        if not options.id and not options.path:
+            raise ValueError("AgentFS.open() requires at least 'id' or 'path'.")
+
+        # Validate agent ID if provided
+        if options.id and not re.match(r"^[a-zA-Z0-9_-]+$", options.id):
+            raise ValueError(
+                "Agent ID must contain only alphanumeric characters, hyphens, and underscores"
+            )
+
+        # Determine database path: explicit path takes precedence, otherwise use id-based path
+        if options.path:
+            db_path = options.path
+        else:
+            # id is guaranteed to be defined here (we checked not id and not path above)
+            directory = ".agentfs"
+            if not os.path.exists(directory):
+                os.makedirs(directory, exist_ok=True)
+            db_path = f"{directory}/{options.id}.db"
+
+        # Connect to the database to ensure it's created
+        db = await connect(db_path)
+
+        return await AgentFS.open_with(db)
+
+    @staticmethod
+    async def open_with(db: Connection) -> "AgentFS":
+        """Open an AgentFS instance with an existing database connection
+
+        Args:
+            db: An existing pyturso.aio Connection
+
+        Returns:
+            Fully initialized AgentFS instance
+        """
+        # Initialize all components in parallel
+        kv = await KvStore.from_database(db)
+        fs = await Filesystem.from_database(db)
+        tools = await ToolCalls.from_database(db)
+
+        return AgentFS(db, kv, fs, tools)
+
+    def get_database(self) -> Connection:
+        """Get the underlying Database connection"""
+        return self._db
+
+    async def close(self) -> None:
+        """Close the database connection"""
+        await self._db.close()
+
+    async def __aenter__(self) -> "AgentFS":
+        """Context manager entry"""
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        """Context manager exit"""
+        await self.close()