aiagentnotes 0.1.0__py3-none-any.whl

aiagentnotes/__init__.py

@@ -0,0 +1,19 @@
+from aiagentnotes.client import AgentNotes
+from aiagentnotes.env import get_client, is_configured, load_env_file, require_client
+from aiagentnotes.paths import (
+    DEFAULT_COMPLETE_PATH,
+    DEFAULT_HEALTH_PATH,
+    DEFAULT_LOG_PATH,
+)
+
+__all__ = [
+    "AgentNotes",
+    "get_client",
+    "require_client",
+    "is_configured",
+    "load_env_file",
+    "DEFAULT_LOG_PATH",
+    "DEFAULT_COMPLETE_PATH",
+    "DEFAULT_HEALTH_PATH",
+]
+__version__ = "0.1.0"

aiagentnotes/client.py

@@ -0,0 +1,240 @@
+"""AgentNotes Python SDK — SparkNotes for your AI agents."""
+
+from __future__ import annotations
+
+import atexit
+import functools
+import os
+import threading
+import traceback
+import uuid
+from typing import Any, Callable, Optional, TypeVar
+
+import requests
+
+from aiagentnotes.env import load_env_file
+from aiagentnotes.paths import DEFAULT_COMPLETE_PATH, DEFAULT_LOG_PATH
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+DEFAULT_BASE_URL = "https://agentnotes.app"
+
+
+def _api_url(base_url: str, path: str) -> str:
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+
+
+class AgentNotes:
+    """Track agent runs and send batched logs to AgentNotes."""
+
+    def __init__(
+        self,
+        api_key: str,
+        agent_id: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        log_path: str = DEFAULT_LOG_PATH,
+        complete_path: str = DEFAULT_COMPLETE_PATH,
+        summary_frequency: str = "daily",
+        batch_size: int = 20,
+        flush_interval: float = 5.0,
+    ) -> None:
+        self.api_key = api_key
+        self.agent_id = agent_id
+        self.base_url = base_url.rstrip("/")
+        self.log_path = log_path
+        self.complete_path = complete_path
+        self.log_url = _api_url(self.base_url, log_path)
+        self.complete_url = _api_url(self.base_url, complete_path)
+        self.summary_frequency = summary_frequency
+        self.batch_size = batch_size
+        self.flush_interval = flush_interval
+
+        self._run_id: Optional[str] = None
+        self._buffer: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            }
+        )
+
+        atexit.register(self.flush)
+
+    @classmethod
+    def from_env(cls) -> AgentNotes:
+        """Build client from AGENTNOTES_* environment variables (Railway, Docker, etc.)."""
+        load_env_file()
+        missing = [
+            name
+            for name, val in (
+                ("AGENTNOTES_API_KEY", os.environ.get("AGENTNOTES_API_KEY")),
+                ("AGENTNOTES_AGENT_ID", os.environ.get("AGENTNOTES_AGENT_ID")),
+            )
+            if not val
+        ]
+        if missing:
+            raise ValueError(f"Missing required env: {', '.join(missing)}")
+
+        return cls(
+            api_key=os.environ["AGENTNOTES_API_KEY"],
+            agent_id=os.environ["AGENTNOTES_AGENT_ID"],
+            base_url=os.environ.get("AGENTNOTES_BASE_URL", DEFAULT_BASE_URL),
+            log_path=os.environ.get("AGENTNOTES_LOG_PATH", DEFAULT_LOG_PATH),
+            complete_path=os.environ.get(
+                "AGENTNOTES_COMPLETE_PATH", DEFAULT_COMPLETE_PATH
+            ),
+        )
+
+    def _ensure_run(self) -> str:
+        if not self._run_id:
+            self._run_id = str(uuid.uuid4())
+        return self._run_id
+
+    def start_run(self, external_run_id: Optional[str] = None) -> str:
+        """Start a new run. Returns the run ID."""
+        self.flush()
+        self._run_id = str(uuid.uuid4())
+        if external_run_id:
+            self.log("run_started", data={"external_run_id": external_run_id})
+        return self._run_id
+
+    def log(
+        self,
+        message: str,
+        *,
+        data: Optional[dict[str, Any]] = None,
+        step_name: Optional[str] = None,
+    ) -> None:
+        """Queue a log event."""
+        self._enqueue(
+            {
+                "step_name": step_name,
+                "event_type": "log",
+                "message": message,
+                "data": data,
+            }
+        )
+
+    def log_error(
+        self,
+        error: BaseException,
+        *,
+        step_name: Optional[str] = None,
+    ) -> None:
+        """Queue an error event."""
+        self._enqueue(
+            {
+                "step_name": step_name,
+                "event_type": "error",
+                "message": str(error),
+                "data": {
+                    "type": type(error).__name__,
+                    "traceback": traceback.format_exc(),
+                },
+            }
+        )
+
+    def _enqueue(self, entry: dict[str, Any]) -> None:
+        with self._lock:
+            self._buffer.append(entry)
+            if len(self._buffer) >= self.batch_size:
+                self._flush_unlocked()
+
+    def flush(self) -> None:
+        """Send buffered logs to the API."""
+        with self._lock:
+            self._flush_unlocked()
+
+    def _flush_unlocked(self) -> None:
+        if not self._buffer:
+            return
+
+        batch = self._buffer[:]
+        self._buffer.clear()
+        run_id = self._ensure_run()
+
+        payload = {
+            "agent_id": self.agent_id,
+            "run_id": run_id,
+            "logs": batch,
+        }
+
+        try:
+            resp = self._session.post(
+                self.log_url,
+                json=payload,
+                timeout=30,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            if data.get("run_id"):
+                self._run_id = data["run_id"]
+        except requests.RequestException:
+            # Re-queue on failure for a best-effort retry
+            self._buffer = batch + self._buffer
+
+    def complete_run(
+        self,
+        result: Optional[Any] = None,
+        *,
+        status: str = "completed",
+        error_message: Optional[str] = None,
+    ) -> None:
+        """Mark the current run as complete and flush remaining logs."""
+        self.flush()
+        if not self._run_id:
+            return
+
+        payload = {
+            "agent_id": self.agent_id,
+            "run_id": self._run_id,
+            "result": result,
+            "status": status,
+            "error_message": error_message,
+        }
+
+        try:
+            resp = self._session.post(
+                self.complete_url,
+                json=payload,
+                timeout=30,
+            )
+            resp.raise_for_status()
+        except requests.RequestException:
+            pass
+        finally:
+            self._run_id = None
+
+    def track(self, step_name: str) -> Callable[[F], F]:
+        """Decorator to track a function as an agent step."""
+
+        def decorator(fn: F) -> F:
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                self._enqueue(
+                    {
+                        "step_name": step_name,
+                        "event_type": "step_start",
+                        "message": f"Starting {step_name}",
+                    }
+                )
+                try:
+                    result = fn(*args, **kwargs)
+                    self._enqueue(
+                        {
+                            "step_name": step_name,
+                            "event_type": "step_end",
+                            "message": f"Completed {step_name}",
+                        }
+                    )
+                    return result
+                except Exception as e:
+                    self.log_error(e, step_name=step_name)
+                    raise
+
+            return wrapper  # type: ignore
+
+        return decorator

aiagentnotes/env.py

@@ -0,0 +1,61 @@
+"""Environment configuration for AgentNotes clients."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Optional
+
+from aiagentnotes.paths import DEFAULT_COMPLETE_PATH, DEFAULT_LOG_PATH
+
+if TYPE_CHECKING:
+    from aiagentnotes.client import AgentNotes
+
+REQUIRED_ENV = ("AGENTNOTES_API_KEY", "AGENTNOTES_AGENT_ID")
+OPTIONAL_ENV = (
+    "AGENTNOTES_BASE_URL",
+    "AGENTNOTES_LOG_PATH",
+    "AGENTNOTES_COMPLETE_PATH",
+)
+
+
+def load_env_file() -> bool:
+    """Load `.env` from the current working directory if python-dotenv is installed."""
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        return False
+    return bool(load_dotenv())
+
+
+def is_configured() -> bool:
+    """True when required AGENTNOTES_* variables are set."""
+    load_env_file()
+    return all(os.environ.get(name) for name in REQUIRED_ENV)
+
+
+def get_client() -> Optional["AgentNotes"]:
+    """
+    Return an AgentNotes client when env is configured, else None.
+    Safe to call in bots that should run without logging when not set up.
+    """
+    if not is_configured():
+        return None
+    from aiagentnotes.client import AgentNotes
+
+    return AgentNotes.from_env()
+
+
+def require_client() -> "AgentNotes":
+    """Like get_client() but raises with a helpful message if env is missing."""
+    client = get_client()
+    if client is not None:
+        return client
+    missing = [name for name in REQUIRED_ENV if not os.environ.get(name)]
+    raise ValueError(
+        "AgentNotes is not configured. Set environment variables:\n"
+        f"  Required: {', '.join(REQUIRED_ENV)}\n"
+        f"  Optional: {', '.join(OPTIONAL_ENV)} (defaults: "
+        f"LOG={DEFAULT_LOG_PATH}, COMPLETE={DEFAULT_COMPLETE_PATH})\n"
+        f"  Missing now: {', '.join(missing)}\n"
+        "Install: pip install aiagentnotes"
+    )

aiagentnotes/integrations/__init__.py

@@ -0,0 +1 @@
+"""Optional integrations for popular agent frameworks."""

aiagentnotes/integrations/crewai.py

@@ -0,0 +1,26 @@
+"""CrewAI step hooks via AgentNotes."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from aiagentnotes.client import AgentNotes
+
+
+def crew_step_logger(notes: AgentNotes, step_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator for CrewAI task functions — same as notes.track but explicit naming."""
+
+    return notes.track(step_name)
+
+
+def log_crew_kickoff(notes: AgentNotes, crew_name: str, **meta: Any) -> str:
+    """Call before crew.kickoff(). Returns run id."""
+    run_id = notes.start_run(external_run_id=crew_name)
+    notes.log("crew_kickoff", data={"crew": crew_name, **meta})
+    return run_id
+
+
+def log_crew_complete(notes: AgentNotes, result: Any) -> None:
+    """Call after crew.kickoff() returns."""
+    summary = str(result)[:500] if result is not None else "completed"
+    notes.complete_run({"summary": summary})

aiagentnotes/integrations/langchain.py

@@ -0,0 +1,126 @@
+"""LangChain callback handler for AgentNotes."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+from uuid import UUID
+
+from aiagentnotes.client import AgentNotes
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+    from langchain_core.agents import AgentAction, AgentFinish
+    from langchain_core.outputs import LLMResult
+except ImportError as e:
+    raise ImportError(
+        "LangChain integration requires langchain-core: pip install langchain-core"
+    ) from e
+
+
+class AgentNotesCallbackHandler(BaseCallbackHandler):
+    """Log LangChain chains, tools, and LLM calls to AgentNotes."""
+
+    def __init__(self, notes: AgentNotes) -> None:
+        super().__init__()
+        self.notes = notes
+        if not notes._run_id:
+            notes.start_run()
+
+    def on_chain_start(
+        self,
+        serialized: Dict[str, Any],
+        inputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        name = serialized.get("name") or serialized.get("id", ["chain"])[-1]
+        self.notes.log(
+            f"chain_start: {name}",
+            step_name=str(name),
+            data={"inputs_keys": list(inputs.keys())},
+        )
+
+    def on_chain_end(
+        self,
+        outputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self.notes.log("chain_end", data={"output_keys": list(outputs.keys())})
+
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        tool = serialized.get("name", "tool")
+        self.notes.log(
+            f"tool_start: {tool}",
+            step_name=tool,
+            data={"input_preview": input_str[:500]},
+        )
+
+    def on_tool_end(
+        self,
+        output: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self.notes.log("tool_end", data={"output_preview": str(output)[:500]})
+
+    def on_tool_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self.notes.log_error(error)
+
+    def on_llm_end(
+        self,
+        response: LLMResult,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self.notes.log("llm_end", data={"generations": len(response.generations)})
+
+    def on_agent_action(
+        self,
+        action: AgentAction,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self.notes.log(
+            f"agent_action: {action.tool}",
+            step_name=action.tool,
+            data={"tool_input": str(action.tool_input)[:300]},
+        )
+
+    def on_agent_finish(
+        self,
+        finish: AgentFinish,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self.notes.log(
+            "agent_finish",
+            data={"output_preview": str(finish.return_values)[:500]},
+        )

aiagentnotes/paths.py

@@ -0,0 +1,5 @@
+"""Default HTTP paths for the AgentNotes Next.js API."""
+
+DEFAULT_LOG_PATH = "/api/v1/logs"
+DEFAULT_COMPLETE_PATH = "/api/v1/runs/complete"
+DEFAULT_HEALTH_PATH = "/api/v1/health"

aiagentnotes-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: aiagentnotes
+Version: 0.1.0
+Summary: SparkNotes for your AI agents — log runs to AgentNotes with one pip install and env vars.
+Project-URL: Homepage, https://github.com/mattmerrick/agentnotes
+Project-URL: Documentation, https://github.com/mattmerrick/agentnotes/tree/main/sdk
+Project-URL: Repository, https://github.com/mattmerrick/agentnotes
+Author-email: AgentNotes <yomatt41@gmail.com>
+License-Expression: MIT
+Keywords: agents,ai,langchain,logging,observability,railway
+Classifier: Development Status :: 4 - Beta
+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
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dotenv'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# AgentNotes Python SDK
+
+SparkNotes for your AI agents. Install once, set env vars, call `AgentNotes.from_env()`.
+
+## Install (PyPI)
+
+```bash
+pip install aiagentnotes
+```
+
+Optional local `.env` support:
+
+```bash
+pip install "aiagentnotes[dotenv]"
+```
+
+## Environment variables
+
+See **[ENV.md](./ENV.md)** for the full list.
+
+**Minimum:**
+
+```bash
+export AGENTNOTES_API_KEY="an_xxxxxxxx"
+export AGENTNOTES_AGENT_ID="my-bot-slug"
+export AGENTNOTES_BASE_URL="https://your-agentnotes.vercel.app"
+```
+
+## Quick start
+
+```python
+from aiagentnotes import AgentNotes
+
+notes = AgentNotes.from_env()
+
+@notes.track("handle_request")
+def handle_request(req):
+    notes.log("received", data={"id": getattr(req, "id", None)})
+    notes.complete_run({"summary": "Done"})
+```
+
+## Optional: logging only when configured
+
+```python
+from aiagentnotes import get_client
+
+notes = get_client()
+if notes:
+    notes.log("bot started")
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `AgentNotes.from_env()` | Build client from `AGENTNOTES_*` env vars |
+| `get_client()` | Same, or `None` if not configured |
+| `require_client()` | Same, or raise with setup instructions |
+| `notes.log(message, ...)` | Log an event |
+| `notes.complete_run(result)` | Finish run |
+| `notes.track("step")` | Decorator for a step |
+
+## Development (this monorepo)
+
+```bash
+cd sdk && pip install -e ".[dev,dotenv]"
+```
+
+## Publish to PyPI
+
+See [../docs/PUBLISHING.md](../docs/PUBLISHING.md).

aiagentnotes-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+aiagentnotes/__init__.py,sha256=fvLUoM4cNmiQdzZDaZvQ1bqXb9Yu_S0Lcnf5XmGU9Mg,455
+aiagentnotes/client.py,sha256=clDxD5pc-TagkHYyFuxNCoW3QNFZaqK06eNQg7GL9r0,7175
+aiagentnotes/env.py,sha256=W38kxhyi6X9NLL9-lc0ih_tHIQnEWJSmDMpLvaOlfLA,1843
+aiagentnotes/paths.py,sha256=NNW4TVbmTCSOqfwWKPTmuruaimdnTGXnwtmjyBI8dNk,179
+aiagentnotes/integrations/__init__.py,sha256=yn0cq43EquaRZkTPgnDl5_20js-JT9afmQlwFOyiOqs,58
+aiagentnotes/integrations/crewai.py,sha256=0volZ8jHSkGea3luvavfbBAdEB0E3eQ9Z5YSn3Ux1YA,890
+aiagentnotes/integrations/langchain.py,sha256=c8tiTWAeWGtgRif7-ycgaFHBOeIRQHO-GZ5rPRGG5Pw,3373
+aiagentnotes-0.1.0.dist-info/METADATA,sha256=OS36zSUg0JXvMXrUwS6VNl-AaZ9JWyoopiiQXPqf9dM,2876
+aiagentnotes-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+aiagentnotes-0.1.0.dist-info/RECORD,,

aiagentnotes-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any