use-lightcurve 0.1.0__tar.gz

use_lightcurve-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: use-lightcurve
+Version: 0.1.0
+Summary: Observability and evaluation SDK for LLM Agents
+Home-page: https://github.com/uselightcurve/lightcurve-sdk
+Author: Lightcurve Team
+Author-email: founders@lightcurve.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: python-dotenv>=0.10.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# use-lightcurve
+
+The official Python SDK for Lightcurve, the observability and evaluation platform for LLM Agents.
+
+## Installation
+
+```bash
+pip install use-lightcurve
+```
+
+## Quick Start
+
+```python
+from lightcurve import Lightcurve
+
+lc = Lightcurve(api_key="your_api_key")
+
+# Track a run
+with lc.trace(agent_id="my-agent") as run:
+    result = my_agent.run("input prompt")
+    run.log_output(result)
+```

use_lightcurve-0.1.0/README.md

@@ -0,0 +1,22 @@
+# use-lightcurve
+
+The official Python SDK for Lightcurve, the observability and evaluation platform for LLM Agents.
+
+## Installation
+
+```bash
+pip install use-lightcurve
+```
+
+## Quick Start
+
+```python
+from lightcurve import Lightcurve
+
+lc = Lightcurve(api_key="your_api_key")
+
+# Track a run
+with lc.trace(agent_id="my-agent") as run:
+    result = my_agent.run("input prompt")
+    run.log_output(result)
+```

use_lightcurve-0.1.0/lightcurve/__init__.py

@@ -0,0 +1,3 @@
+from .tracer import tracer
+
+__all__ = ["tracer"]

use_lightcurve-0.1.0/lightcurve/buffer.py

@@ -0,0 +1,81 @@
+import threading
+import queue
+import time
+import requests # using sync requests in thread
+from typing import List, Optional
+from .schemas import CognitionEvent
+
+class EventBuffer:
+    def __init__(self, api_url: str, api_key: Optional[str] = None, batch_size: int = 10, flush_interval: float = 2.0):
+        self.api_url = api_url
+        self.api_key = api_key
+        self.batch_size = batch_size
+        self.flush_interval = flush_interval
+        
+        self._queue: queue.Queue[CognitionEvent] = queue.Queue()
+        self._stop_event = threading.Event()
+        self._worker_thread = threading.Thread(target=self._worker_loop, daemon=True)
+        self._worker_thread.start()
+
+    def add_event(self, event: CognitionEvent):
+        self._queue.put(event)
+
+    def flush(self):
+        """Force flush all events in queue."""
+        # Simple implementation: wait for queue to be empty
+        # In a real system we might pause specific ingestion to flush.
+        # Here we just wait a bit or could trigger immediate send.
+        self._queue.join()
+
+    def close(self):
+        self._stop_event.set()
+        self._worker_thread.join(timeout=5.0)
+
+    def _worker_loop(self):
+        batch = []
+        last_flush = time.time()
+
+        while not self._stop_event.is_set():
+            try:
+                # Wait for items nicely
+                try:
+                    event = self._queue.get(timeout=0.5)
+                    batch.append(event)
+                except queue.Empty:
+                    pass
+
+                current_time = time.time()
+                is_batch_full = len(batch) >= self.batch_size
+                is_time_to_flush = (current_time - last_flush) >= self.flush_interval and len(batch) > 0
+
+                if is_batch_full or is_time_to_flush:
+                    self._send_batch(batch)
+                    # Mark tasks as done in queue
+                    for _ in range(len(batch)):
+                        self._queue.task_done()
+                    batch = []
+                    last_flush = current_time
+
+            except Exception as e:
+                print(f"[Lightcurve] Error in buffer worker: {e}")
+
+        # Final flush on exit
+        if batch:
+            self._send_batch(batch)
+
+    def _send_batch(self, batch: List[CognitionEvent]):
+        try:
+            payload = {
+                "events": [event.model_dump(mode='json') for event in batch]
+            }
+            # Assuming api_url is the base url, e.g., http://localhost:8000
+            endpoint = f"{self.api_url}/v1/ingest"
+            headers = {"Content-Type": "application/json"}
+            if self.api_key:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            
+            response = requests.post(endpoint, json=payload, headers=headers, timeout=10)
+            response.raise_for_status()
+        except Exception as e:
+            # In a real system, we would retry or retry-backoff
+            print(f"[Lightcurve] Failed to send batch: {e}")

use_lightcurve-0.1.0/lightcurve/client.py

@@ -0,0 +1,75 @@
+import uuid
+from typing import List, Optional, Dict, Any
+from datetime import datetime, timezone
+
+from .schemas import (
+    CognitionEvent, InputPayload, KnowledgePayload, PlanPayload, 
+    ToolPayload, ValidationPayload, OutputPayload, IncidentFlags
+)
+from .buffer import EventBuffer
+
+class Lightcurve:
+    def __init__(self, api_key: Optional[str] = None, base_url: str = "http://localhost:8000"):
+        self.api_key = api_key
+        self.base_url = base_url
+        self.buffer = EventBuffer(api_url=base_url, api_key=api_key)
+
+    def start_run(self, agent_id: str, run_id: Optional[str] = None, org_id: Optional[str] = None) -> 'Run':
+        if not run_id:
+            run_id = str(uuid.uuid4())
+        return Run(client=self, run_id=run_id, agent_id=agent_id, org_id=org_id)
+
+    def close(self):
+        self.buffer.close()
+
+class Run:
+    def __init__(self, client: Lightcurve, run_id: str, agent_id: str, org_id: Optional[str] = None):
+        self.client = client
+        self.run_id = run_id
+        self.agent_id = agent_id
+        self.org_id = org_id
+
+    def _log(self, type: str, data: Any, incident_flags: Optional[IncidentFlags] = None):
+        event = CognitionEvent(
+            run_id=self.run_id,
+            agent_id=self.agent_id,
+            org_id=self.org_id,
+            timestamp=datetime.now(timezone.utc),
+            type=type,
+            data=data,
+            incident_flags=incident_flags
+        )
+        self.client.buffer.add_event(event)
+
+    def log_input(self, user_input: str, interpreted_goal: Optional[str] = None, constraints: List[str] = []):
+        data = InputPayload(user_input=user_input, interpreted_goal=interpreted_goal, constraints=constraints)
+        self._log("input", data)
+
+    def log_knowledge(self, summary: str, evidence_present: bool = False, sources: List[str] = []):
+        data = KnowledgePayload(summary=summary, evidence_present=evidence_present, sources=sources)
+        self._log("knowledge", data)
+
+    def log_plan(self, steps: List[str], rationale: Optional[str] = None, alternatives: List[str] = []):
+        data = PlanPayload(steps=steps, rationale=rationale, alternatives=alternatives)
+        self._log("plan", data)
+
+    def log_tool(self, tool_name: str, input: Dict[str, Any], output: Optional[Dict[str, Any]] = None, 
+                 success: bool = True, retries: int = 0, latency_ms: Optional[float] = None):
+        data = ToolPayload(
+            tool_name=tool_name, input=input, output=output, 
+            success=success, retries=retries, latency_ms=latency_ms
+        )
+        self._log("tool", data)
+
+    def log_validation(self, result: bool, method: str = "auto", confidence_score: Optional[float] = None):
+        data = ValidationPayload(result=result, method=method, confidence_score=confidence_score)
+        self._log("validation", data)
+
+    def log_output(self, content: str, structured_data: Optional[Dict[str, Any]] = None, 
+                   confidence: Optional[float] = None):
+        data = OutputPayload(content=content, structured_data=structured_data, confidence=confidence)
+        self._log("output", data)
+
+    def end(self):
+        # Flush the buffer to ensure all events are sent
+        self.client.buffer.flush()

use_lightcurve-0.1.0/lightcurve/context.py

@@ -0,0 +1,9 @@
+from contextvars import ContextVar
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass, field
+
+@dataclass
+class active_run_context:
+    steps: List[Dict[str, Any]] = field(default_factory=list)
+    
+run_ctx = ContextVar("lightcurve_run_ctx", default=None)

use_lightcurve-0.1.0/lightcurve/schemas.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+from typing import List, Optional, Dict, Any, Literal
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+class StepPayload(BaseModel):
+    name: str
+    type: str # "tool", "llm", "planning", "custom"
+    stage: Optional[str] = None # Mapped to backend stage
+    cognitive_type: Optional[str] = None # Cognitive phase
+    status: str # "success", "failure"
+    input: Optional[Dict[str, Any]] = None
+    output: Optional[Dict[str, Any]] = None
+    content: Optional[Dict[str, Any]] = None # Generic content container for persistence
+    duration_ms: Optional[float] = None
+    started_at: Optional[datetime] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+class RunPayload(BaseModel):
+    run_id: str
+    name: str
+    org_id: str = "default-org" # Default for single-tenant / local
+    agent_id: str # Mapped from name if not provided
+    project: Optional[str] = None
+    input: Optional[Dict[str, Any]] = None
+    output: Optional[Dict[str, Any]] = None
+    status: str # "success", "failure"
+    duration_ms: Optional[float] = None
+    started_at: datetime
+    steps: List[StepPayload] = Field(default_factory=list)
+    metadata: Optional[Dict[str, Any]] = None
+    exception: Optional[str] = None

use_lightcurve-0.1.0/lightcurve/tracer.py

@@ -0,0 +1,160 @@
+import os
+import uuid
+import time
+import functools
+import datetime
+from contextvars import ContextVar
+from typing import Optional, Dict, Any, List, Union
+from .transport import BackgroundTransport
+from .schemas import RunPayload, StepPayload
+from .context import run_ctx
+
+
+COGNITIVE_PHASES = {
+    "planning",
+    "goal_decomposition",
+    "reflection",
+    "self_critique",
+    "tool_selection",
+    "validation",
+    "synthesis"
+}
+
+class GlobalTracer:
+    def __init__(self):
+        self.transport: Optional[BackgroundTransport] = None
+        self._api_key: Optional[str] = None
+        self.project: Optional[str] = None
+
+    def init(self, api_key: Optional[str] = None, base_url: str = "http://localhost:8000"):
+        self._api_key = api_key or os.getenv("LIGHTCURVE_API_KEY")
+        self.transport = BackgroundTransport(api_key=self._api_key, api_url=base_url)
+
+    def trace(self, name: Optional[str] = None, project: Optional[str] = None, tags: Optional[Dict[str, Any]] = None):
+        def decorator(func):
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                if not self.transport:
+                    # If not inited, just run the function
+                    return func(*args, **kwargs)
+
+                status = "success"
+                error_msg = None
+                output = None
+                
+                # Start Run
+                start_time = time.time()
+                run_id = str(uuid.uuid4())
+                
+                # Set Context
+                token = run_ctx.set([]) # Initialize steps list
+                
+                try:
+                    result = func(*args, **kwargs)
+                    output = {"return_value": str(result)} # Simplistic stringification
+                    return result
+                except Exception as e:
+                    status = "failure"
+                    error_msg = str(e)
+                    output = {"error": error_msg}
+                    raise e
+                finally:
+                    duration_ms = (time.time() - start_time) * 1000
+                    steps = run_ctx.get()
+                    run_ctx.reset(token)
+
+                    # Build Payload
+                    payload = RunPayload(
+                        run_id=run_id,
+                        name=name or func.__name__,
+                        agent_id=name or func.__name__, # Trace name = agent_id for now
+                        org_id="default-org",
+                        project=project or self.project,
+                        started_at=datetime.datetime.now(datetime.timezone.utc),
+                        duration_ms=duration_ms,
+                        status=status,
+                        input={"args": str(args), "kwargs": str(kwargs)}, # Redact in prod
+                        output=output,
+                        steps=steps, # now this is List[StepPayload]
+                        metadata=tags,
+                        exception=error_msg
+                    )
+                    
+                    # Send
+                    self.transport.send(payload)
+            
+            return wrapper
+        return decorator
+
+    def step(self, name: str, type: str = "custom", metadata: Optional[Dict[str, Any]] = None):
+        return StepContext(name, type, metadata)
+
+    def cognitive(self, phase: str, name: Optional[str] = None):
+        if phase not in COGNITIVE_PHASES:
+            # Soft warning
+            print(f"Warning: Unknown cognitive phase '{phase}'. Expected one of {COGNITIVE_PHASES}")
+        return StepContext(name or phase, "cognitive", {"cognitive_phase": phase})
+
+class StepContext:
+    def __init__(self, name: str, type: str, metadata: Optional[Dict[str, Any]]):
+        self.name = name
+        self.type = type
+        self.metadata = metadata or {}
+        self.start_time = None
+        self.cognitive_type = None
+
+        if type == "cognitive":
+             self.cognitive_type = self.metadata.get("cognitive_phase")
+
+    def __enter__(self):
+        self.start_time = time.time()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        duration = (time.time() - self.start_time) * 1000
+        steps = run_ctx.get()
+        
+        # Map SDK type to Backend Stage
+        stage_map = {
+            "llm": "execution_strategy", 
+            "planning": "task_specification",
+            "custom": "execution_strategy",
+            "cognitive": "execution_strategy" # Default mapping for cognitive steps if not overridden
+        }
+        
+        # If it's a cognitive step, map based on phase if needed, or keep generic stage
+        # For V1, let's map cognitive phases to stages roughly
+        if self.cognitive_type:
+            stage_map_cognitive = {
+                "planning": "task_specification",
+                "goal_decomposition": "task_specification",
+                "reflection": "validation",
+                "self_critique": "validation",
+                "validation": "validation",
+                "tool_selection": "tool_call",
+                "synthesis": "output"
+            }
+            stage = stage_map_cognitive.get(self.cognitive_type, "execution_strategy")
+        else:
+            stage = stage_map.get(self.type, "execution_strategy")
+        
+        if steps is not None:
+            steps.append(StepPayload(
+                name=self.name,
+                type=self.type,
+                stage=stage,
+                cognitive_type=self.cognitive_type,
+                status="failure" if exc_type else "success",
+                started_at=datetime.datetime.now(datetime.timezone.utc),
+                duration_ms=duration,
+                metadata=self.metadata,
+                input={}, # Optionally capture
+                output={"error": str(exc_val)} if exc_val else {},
+                content={
+                    "input": {},
+                    "output": {"error": str(exc_val)} if exc_val else {}
+                }
+            ))
+
+# Global Singleton
+tracer = GlobalTracer()

use_lightcurve-0.1.0/lightcurve/transport.py

@@ -0,0 +1,53 @@
+import threading
+import queue
+import time
+import requests
+from typing import Dict, Any, Optional
+from .schemas import RunPayload
+
+class BackgroundTransport:
+    def __init__(self, api_key: Optional[str], api_url: str = "http://localhost:8000"):
+        self.api_key = api_key
+        self.api_url = api_url.rstrip("/")
+        self._queue: queue.Queue[RunPayload] = queue.Queue()
+        self._stop_event = threading.Event()
+        self._thread = threading.Thread(target=self._worker, daemon=True)
+        self._thread.start()
+
+    def send(self, payload: RunPayload):
+        self._queue.put(payload)
+
+    def close(self):
+        self._stop_event.set()
+        self._thread.join(timeout=2.0)
+
+    def _worker(self):
+        while not self._stop_event.is_set():
+            try:
+                payload = self._queue.get(timeout=1.0)
+                self._post_payload(payload)
+                self._queue.task_done()
+            except queue.Empty:
+                continue
+            except Exception as e:
+                # In production, we should log this properly or use a dead-letter queue
+                # For now, we print to stderr if it's critical, or silent in production
+                pass
+
+    def _post_payload(self, payload: RunPayload):
+        # Retry logic could go here (3x exponential backoff)
+        url = f"{self.api_url}/ingest/trajectory" 
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": self.api_key or "" 
+        }
+
+        try:
+            # We dump to json using Pydantic
+            data = payload.model_dump(mode='json')
+            resp = requests.post(url, json=data, headers=headers, timeout=5)
+            if resp.status_code >= 400:
+                print(f"Error sending trace: {resp.status_code} {resp.text}")
+        except Exception as e:
+            print(f"Network error sending trace: {e}")
+            pass

use_lightcurve-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

use_lightcurve-0.1.0/setup.py

@@ -0,0 +1,23 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="use-lightcurve",
+    version="0.1.0",
+    author="Lightcurve Team",
+    author_email="founders@lightcurve.ai",
+    description="Observability and evaluation SDK for LLM Agents",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/uselightcurve/lightcurve-sdk",
+    packages=find_packages(),
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires='>=3.7',
+    install_requires=[
+        "requests>=2.25.0",
+        "python-dotenv>=0.10.0" 
+    ],
+)

use_lightcurve-0.1.0/use_lightcurve.egg-info/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: use-lightcurve
+Version: 0.1.0
+Summary: Observability and evaluation SDK for LLM Agents
+Home-page: https://github.com/uselightcurve/lightcurve-sdk
+Author: Lightcurve Team
+Author-email: founders@lightcurve.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: python-dotenv>=0.10.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# use-lightcurve
+
+The official Python SDK for Lightcurve, the observability and evaluation platform for LLM Agents.
+
+## Installation
+
+```bash
+pip install use-lightcurve
+```
+
+## Quick Start
+
+```python
+from lightcurve import Lightcurve
+
+lc = Lightcurve(api_key="your_api_key")
+
+# Track a run
+with lc.trace(agent_id="my-agent") as run:
+    result = my_agent.run("input prompt")
+    run.log_output(result)
+```

use_lightcurve-0.1.0/use_lightcurve.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+setup.py
+lightcurve/__init__.py
+lightcurve/buffer.py
+lightcurve/client.py
+lightcurve/context.py
+lightcurve/schemas.py
+lightcurve/tracer.py
+lightcurve/transport.py
+use_lightcurve.egg-info/PKG-INFO
+use_lightcurve.egg-info/SOURCES.txt
+use_lightcurve.egg-info/dependency_links.txt
+use_lightcurve.egg-info/requires.txt
+use_lightcurve.egg-info/top_level.txt

use_lightcurve-0.1.0/use_lightcurve.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

use_lightcurve-0.1.0/use_lightcurve.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests>=2.25.0
+python-dotenv>=0.10.0

use_lightcurve-0.1.0/use_lightcurve.egg-info/top_level.txt

@@ -0,0 +1 @@
+lightcurve