agentlog-sdk 0.1.0__tar.gz

agentlog_sdk-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Build output
+bin/
+
+# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+dist/
+
+# MkDocs build output
+docs-site/site/
+
+# agentlog data (local runtime state)
+*.pid
+*.sock

agentlog_sdk-0.1.0/LICENSE

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

agentlog_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: agentlog-sdk
+Version: 0.1.0
+Summary: Python SDK for agentlog - a local-first decision log daemon for agentic workflows
+Project-URL: Homepage, https://byronxlg.github.io/agentlog/
+Project-URL: Documentation, https://byronxlg.github.io/agentlog/docs/
+Project-URL: Repository, https://github.com/byronxlg/agentlog
+Project-URL: Issues, https://github.com/byronxlg/agentlog/issues
+Author: agentlog contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,agentic,decision-log,llm,logging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# agentlog Python SDK
+
+Python client for [agentlog](https://github.com/byronxlg/agentlog) - a local-first decision log daemon for agentic workflows.
+
+## Installation
+
+```bash
+pip install agentlog-sdk
+```
+
+## Quickstart
+
+```python
+import agentlog
+
+agentlog.write("decision", "Use PostgreSQL for persistence")
+entries = agentlog.query("database")
+```
+
+## Requirements
+
+- Python 3.9+
+- A running `agentlogd` daemon (see the main project README)
+
+## Usage
+
+### Writing entries
+
+```python
+import agentlog
+
+# Write a decision entry (session created automatically)
+agentlog.write(
+    "decision",
+    "Use Redis for caching",
+    body="Redis provides sub-millisecond reads and built-in TTL support.",
+    tags=["infrastructure", "caching"],
+    files=["config/redis.yaml"],
+)
+
+# Supported entry types: decision, attempt_failed, deferred, assumption, question
+agentlog.write("assumption", "All users have Python 3.9+")
+agentlog.write("question", "Should we use async or sync HTTP client?")
+```
+
+### Searching entries
+
+```python
+# Full-text search
+results = agentlog.query("database migration")
+
+# Search with filters
+results = agentlog.query("caching", type="decision", limit=5)
+```
+
+### Listing entries
+
+```python
+# List entries by type
+entries = agentlog.log(type="decision")
+
+# List entries by session
+entries = agentlog.log(session="your-session-id")
+
+# List entries by tag
+entries = agentlog.log(tag="infrastructure")
+
+# List entries from the last hour
+entries = agentlog.log(since="1h")
+```
+
+### Getting context for prompts
+
+```python
+# Get a formatted text block for prompt injection
+context = agentlog.context(query="authentication")
+print(context)
+# Output:
+# # Recent decisions
+#
+# ## [decision] Use JWT for API auth (2026-03-15 10:30)
+# JWTs are stateless and work well with our microservices architecture.
+# Tags: auth, api
+# Files: internal/auth/jwt.go
+```
+
+### Using the client class directly
+
+```python
+from agentlog import AgentlogClient
+
+# Custom socket path
+client = AgentlogClient(agentlog_dir="/custom/path")
+
+# Or explicit socket path
+client = AgentlogClient(socket_path="/tmp/agentlogd.sock")
+
+# All methods are available on the client instance
+entry_id = client.write("decision", "Use gRPC for internal services")
+```
+
+### Configuration
+
+The SDK looks for the daemon socket at `~/.agentlog/agentlogd.sock` by default.
+Override this with:
+
+- The `AGENTLOG_DIR` environment variable
+- The `agentlog_dir` constructor argument
+- The `socket_path` constructor argument (takes precedence)
+
+### Error handling
+
+```python
+from agentlog import AgentlogError, ConnectionError, DaemonNotRunning
+
+try:
+    agentlog.write("decision", "Test entry")
+except DaemonNotRunning:
+    print("Start the daemon first: agentlog start")
+except ConnectionError as e:
+    print(f"Connection failed: {e}")
+except AgentlogError as e:
+    print(f"Unexpected error: {e}")
+```
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e sdk/python/
+
+# Run tests
+python -m pytest sdk/python/tests/ -v
+
+# Run only unit tests (no daemon required)
+python -m pytest sdk/python/tests/test_client.py -v
+```

agentlog_sdk-0.1.0/README.md

@@ -0,0 +1,137 @@
+# agentlog Python SDK
+
+Python client for [agentlog](https://github.com/byronxlg/agentlog) - a local-first decision log daemon for agentic workflows.
+
+## Installation
+
+```bash
+pip install agentlog-sdk
+```
+
+## Quickstart
+
+```python
+import agentlog
+
+agentlog.write("decision", "Use PostgreSQL for persistence")
+entries = agentlog.query("database")
+```
+
+## Requirements
+
+- Python 3.9+
+- A running `agentlogd` daemon (see the main project README)
+
+## Usage
+
+### Writing entries
+
+```python
+import agentlog
+
+# Write a decision entry (session created automatically)
+agentlog.write(
+    "decision",
+    "Use Redis for caching",
+    body="Redis provides sub-millisecond reads and built-in TTL support.",
+    tags=["infrastructure", "caching"],
+    files=["config/redis.yaml"],
+)
+
+# Supported entry types: decision, attempt_failed, deferred, assumption, question
+agentlog.write("assumption", "All users have Python 3.9+")
+agentlog.write("question", "Should we use async or sync HTTP client?")
+```
+
+### Searching entries
+
+```python
+# Full-text search
+results = agentlog.query("database migration")
+
+# Search with filters
+results = agentlog.query("caching", type="decision", limit=5)
+```
+
+### Listing entries
+
+```python
+# List entries by type
+entries = agentlog.log(type="decision")
+
+# List entries by session
+entries = agentlog.log(session="your-session-id")
+
+# List entries by tag
+entries = agentlog.log(tag="infrastructure")
+
+# List entries from the last hour
+entries = agentlog.log(since="1h")
+```
+
+### Getting context for prompts
+
+```python
+# Get a formatted text block for prompt injection
+context = agentlog.context(query="authentication")
+print(context)
+# Output:
+# # Recent decisions
+#
+# ## [decision] Use JWT for API auth (2026-03-15 10:30)
+# JWTs are stateless and work well with our microservices architecture.
+# Tags: auth, api
+# Files: internal/auth/jwt.go
+```
+
+### Using the client class directly
+
+```python
+from agentlog import AgentlogClient
+
+# Custom socket path
+client = AgentlogClient(agentlog_dir="/custom/path")
+
+# Or explicit socket path
+client = AgentlogClient(socket_path="/tmp/agentlogd.sock")
+
+# All methods are available on the client instance
+entry_id = client.write("decision", "Use gRPC for internal services")
+```
+
+### Configuration
+
+The SDK looks for the daemon socket at `~/.agentlog/agentlogd.sock` by default.
+Override this with:
+
+- The `AGENTLOG_DIR` environment variable
+- The `agentlog_dir` constructor argument
+- The `socket_path` constructor argument (takes precedence)
+
+### Error handling
+
+```python
+from agentlog import AgentlogError, ConnectionError, DaemonNotRunning
+
+try:
+    agentlog.write("decision", "Test entry")
+except DaemonNotRunning:
+    print("Start the daemon first: agentlog start")
+except ConnectionError as e:
+    print(f"Connection failed: {e}")
+except AgentlogError as e:
+    print(f"Unexpected error: {e}")
+```
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e sdk/python/
+
+# Run tests
+python -m pytest sdk/python/tests/ -v
+
+# Run only unit tests (no daemon required)
+python -m pytest sdk/python/tests/test_client.py -v
+```

agentlog_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentlog-sdk"
+version = "0.1.0"
+description = "Python SDK for agentlog - a local-first decision log daemon for agentic workflows"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "agentlog contributors" },
+]
+keywords = ["agent", "logging", "decision-log", "llm", "agentic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "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",
+]
+
+[project.urls]
+Homepage = "https://byronxlg.github.io/agentlog/"
+Documentation = "https://byronxlg.github.io/agentlog/docs/"
+Repository = "https://github.com/byronxlg/agentlog"
+Issues = "https://github.com/byronxlg/agentlog/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentlog"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

agentlog_sdk-0.1.0/src/agentlog/__init__.py

@@ -0,0 +1,117 @@
+"""agentlog - Python SDK for the agentlog decision log daemon.
+
+Usage::
+
+    import agentlog
+
+    agentlog.write("decision", "Use PostgreSQL for persistence")
+    entries = agentlog.query("database")
+"""
+
+from __future__ import annotations
+
+from .client import AgentlogClient, VALID_ENTRY_TYPES
+from .errors import AgentlogError, ConnectionError, DaemonNotRunning
+
+__all__ = [
+    "AgentlogClient",
+    "AgentlogError",
+    "ConnectionError",
+    "DaemonNotRunning",
+    "VALID_ENTRY_TYPES",
+    "write",
+    "query",
+    "log",
+    "context",
+]
+
+_default_client: AgentlogClient | None = None
+
+
+def _get_default_client() -> AgentlogClient:
+    """Return the module-level default client, creating it on first use."""
+    global _default_client
+    if _default_client is None:
+        _default_client = AgentlogClient()
+    return _default_client
+
+
+def write(
+    type: str,
+    title: str,
+    body: str | None = None,
+    tags: list[str] | None = None,
+    files: list[str] | None = None,
+    session: str | None = None,
+) -> str:
+    """Write a decision entry to the log.
+
+    Convenience wrapper around :meth:`AgentlogClient.write` using the
+    module-level default client.
+
+    Args:
+        type: Entry type (decision, attempt_failed, deferred, assumption, question).
+        title: Short summary of the decision.
+        body: Optional longer description.
+        tags: Optional list of tags.
+        files: Optional list of file references.
+        session: Optional session ID.
+
+    Returns:
+        The ID of the written entry.
+    """
+    return _get_default_client().write(
+        type=type, title=title, body=body, tags=tags, files=files, session=session,
+    )
+
+
+def query(
+    text: str,
+    type: str | None = None,
+    session: str | None = None,
+    tag: str | None = None,
+    file: str | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    limit: int = 20,
+) -> list[dict]:
+    """Full-text search for entries.
+
+    Convenience wrapper around :meth:`AgentlogClient.query`.
+    """
+    return _get_default_client().query(
+        text=text, type=type, session=session, tag=tag, file=file,
+        since=since, until=until, limit=limit,
+    )
+
+
+def log(
+    type: str | None = None,
+    session: str | None = None,
+    tag: str | None = None,
+    file: str | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> list[dict]:
+    """List entries with filters.
+
+    Convenience wrapper around :meth:`AgentlogClient.log`.
+    """
+    return _get_default_client().log(
+        type=type, session=session, tag=tag, file=file,
+        since=since, until=until, limit=limit, offset=offset,
+    )
+
+
+def context(
+    query: str | None = None,
+    session: str | None = None,
+    limit: int = 10,
+) -> str:
+    """Return a structured context string suitable for prompt injection.
+
+    Convenience wrapper around :meth:`AgentlogClient.context`.
+    """
+    return _get_default_client().context(query=query, session=session, limit=limit)