clientcoded 0.1.0__tar.gz

clientcoded-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: clientcoded
+Version: 0.1.0
+Summary: ClientCoded SDK - Trace your AI agent's tool calls for root cause analysis
+Home-page: https://github.com/ClientCoded/clientcoded-python
+Author: ClientCoded
+Author-email: travis@clientcoded.com
+Keywords: ai agent testing qa tracing evaluation
+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.8
+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: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# ClientCoded Python SDK
+
+Trace your AI agent's tool calls for root cause analysis when failures occur.
+
+## Install
+
+```bash
+pip install clientcoded
+```
+
+## Quick Start
+
+```python
+import clientcoded
+
+# Configure once at startup
+clientcoded.configure(
+    agent_id="your-agent-id",
+    api_key="your-api-key"
+)
+
+# Decorate any function your agent calls
+@clientcoded.trace
+def get_invoice(invoice_id):
+    return stripe.Invoice.retrieve(invoice_id)
+
+@clientcoded.trace
+def search_knowledge_base(query):
+    return pinecone.query(query)
+
+@clientcoded.trace
+def update_crm(contact_id, data):
+    return hubspot.update_contact(contact_id, data)
+```
+
+## Conversation Tracking
+
+```python
+# At the start of each conversation
+clientcoded.set_conversation_id("conv-123")
+
+# At each turn
+clientcoded.set_turn(1)
+response = agent.handle_message("What is my invoice total?")
+
+clientcoded.set_turn(2)
+response = agent.handle_message("Can you break that down by line item?")
+```
+
+## Async Support
+
+```python
+@clientcoded.trace_async
+async def get_invoice(invoice_id):
+    return await stripe.Invoice.aretrieve(invoice_id)
+```
+
+## Custom Names
+
+```python
+@clientcoded.trace(name="stripe_invoice_lookup")
+def get_invoice(invoice_id):
+    return stripe.Invoice.retrieve(invoice_id)
+```
+
+## Manual Logging
+
+For complex operations where decorators don't fit:
+
+```python
+import time
+
+start = time.time()
+try:
+    result = complex_multi_step_operation()
+    clientcoded.log_trace(
+        "complex_operation",
+        input_data={"step": "final"},
+        output_data=result,
+        latency_ms=int((time.time() - start) * 1000)
+    )
+except Exception as e:
+    clientcoded.log_trace(
+        "complex_operation",
+        input_data={"step": "final"},
+        error=str(e),
+        latency_ms=int((time.time() - start) * 1000)
+    )
+    raise
+```
+
+## LangChain Integration
+
+```python
+from langchain.tools import tool
+import clientcoded
+
+clientcoded.configure(agent_id="your-agent-id", api_key="your-api-key")
+
+@tool
+@clientcoded.trace
+def search_database(query: str) -> str:
+    """Search the company database."""
+    return db.execute(query)
+```
+
+## LlamaIndex Integration
+
+```python
+from llama_index.core.tools import FunctionTool
+import clientcoded
+
+clientcoded.configure(agent_id="your-agent-id", api_key="your-api-key")
+
+@clientcoded.trace
+def query_index(question: str) -> str:
+    return index.query(question)
+
+tool = FunctionTool.from_defaults(fn=query_index)
+```
+
+## What Gets Traced
+
+For each decorated function call, the SDK logs:
+- Function name (or custom name)
+- Input arguments (truncated to 2000 chars)
+- Output (truncated to 2000 chars)
+- Error message if the function threw
+- Latency in milliseconds
+- Conversation ID and turn number (if set)
+
+## What Doesn't Get Traced
+
+- The SDK never captures environment variables
+- The SDK never captures file contents
+- Large inputs/outputs are truncated, not stored in full
+- All trace sends are fire-and-forget with a 2-second timeout
+
+## Safety
+
+- The SDK will **never** break your agent. Every trace send is wrapped in try/catch.
+- Trace sends happen in background threads. Zero impact on response latency.
+- If the ClientCoded API is down, traces are silently dropped. Your agent continues normally.
+- No sensitive data filtering in v0.1. Do not decorate functions that handle passwords, tokens, or PII directly. Wrap them in a function that sanitizes first.
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| CLIENTCODED_TRACE_URL | https://clientcoded.app.n8n.cloud/webhook/ap-35-trace-ingest | Custom trace endpoint |

clientcoded-0.1.0/README.md

@@ -0,0 +1,150 @@
+# ClientCoded Python SDK
+
+Trace your AI agent's tool calls for root cause analysis when failures occur.
+
+## Install
+
+```bash
+pip install clientcoded
+```
+
+## Quick Start
+
+```python
+import clientcoded
+
+# Configure once at startup
+clientcoded.configure(
+    agent_id="your-agent-id",
+    api_key="your-api-key"
+)
+
+# Decorate any function your agent calls
+@clientcoded.trace
+def get_invoice(invoice_id):
+    return stripe.Invoice.retrieve(invoice_id)
+
+@clientcoded.trace
+def search_knowledge_base(query):
+    return pinecone.query(query)
+
+@clientcoded.trace
+def update_crm(contact_id, data):
+    return hubspot.update_contact(contact_id, data)
+```
+
+## Conversation Tracking
+
+```python
+# At the start of each conversation
+clientcoded.set_conversation_id("conv-123")
+
+# At each turn
+clientcoded.set_turn(1)
+response = agent.handle_message("What is my invoice total?")
+
+clientcoded.set_turn(2)
+response = agent.handle_message("Can you break that down by line item?")
+```
+
+## Async Support
+
+```python
+@clientcoded.trace_async
+async def get_invoice(invoice_id):
+    return await stripe.Invoice.aretrieve(invoice_id)
+```
+
+## Custom Names
+
+```python
+@clientcoded.trace(name="stripe_invoice_lookup")
+def get_invoice(invoice_id):
+    return stripe.Invoice.retrieve(invoice_id)
+```
+
+## Manual Logging
+
+For complex operations where decorators don't fit:
+
+```python
+import time
+
+start = time.time()
+try:
+    result = complex_multi_step_operation()
+    clientcoded.log_trace(
+        "complex_operation",
+        input_data={"step": "final"},
+        output_data=result,
+        latency_ms=int((time.time() - start) * 1000)
+    )
+except Exception as e:
+    clientcoded.log_trace(
+        "complex_operation",
+        input_data={"step": "final"},
+        error=str(e),
+        latency_ms=int((time.time() - start) * 1000)
+    )
+    raise
+```
+
+## LangChain Integration
+
+```python
+from langchain.tools import tool
+import clientcoded
+
+clientcoded.configure(agent_id="your-agent-id", api_key="your-api-key")
+
+@tool
+@clientcoded.trace
+def search_database(query: str) -> str:
+    """Search the company database."""
+    return db.execute(query)
+```
+
+## LlamaIndex Integration
+
+```python
+from llama_index.core.tools import FunctionTool
+import clientcoded
+
+clientcoded.configure(agent_id="your-agent-id", api_key="your-api-key")
+
+@clientcoded.trace
+def query_index(question: str) -> str:
+    return index.query(question)
+
+tool = FunctionTool.from_defaults(fn=query_index)
+```
+
+## What Gets Traced
+
+For each decorated function call, the SDK logs:
+- Function name (or custom name)
+- Input arguments (truncated to 2000 chars)
+- Output (truncated to 2000 chars)
+- Error message if the function threw
+- Latency in milliseconds
+- Conversation ID and turn number (if set)
+
+## What Doesn't Get Traced
+
+- The SDK never captures environment variables
+- The SDK never captures file contents
+- Large inputs/outputs are truncated, not stored in full
+- All trace sends are fire-and-forget with a 2-second timeout
+
+## Safety
+
+- The SDK will **never** break your agent. Every trace send is wrapped in try/catch.
+- Trace sends happen in background threads. Zero impact on response latency.
+- If the ClientCoded API is down, traces are silently dropped. Your agent continues normally.
+- No sensitive data filtering in v0.1. Do not decorate functions that handle passwords, tokens, or PII directly. Wrap them in a function that sanitizes first.
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| CLIENTCODED_TRACE_URL | https://clientcoded.app.n8n.cloud/webhook/ap-35-trace-ingest | Custom trace endpoint |

clientcoded-0.1.0/clientcoded/__init__.py

@@ -0,0 +1,20 @@
+from .trace import (
+    configure,
+    set_conversation_id,
+    set_turn,
+    increment_turn,
+    trace,
+    trace_async,
+    log_trace,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "configure",
+    "set_conversation_id",
+    "set_turn",
+    "increment_turn",
+    "trace",
+    "trace_async",
+    "log_trace",
+]

clientcoded-0.1.0/clientcoded/trace.py

@@ -0,0 +1,225 @@
+# ClientCoded Python SDK
+# pip install clientcoded
+
+import requests
+import functools
+import time
+import uuid
+import threading
+import os
+
+CLIENTCODED_API = os.environ.get(
+    "CLIENTCODED_TRACE_URL",
+    "https://clientcoded.app.n8n.cloud/webhook/ap-35-trace-ingest"
+)
+
+_context = threading.local()
+
+
+def configure(agent_id, api_key, trace_url=None):
+    """
+    Configure the SDK globally.
+    
+    Args:
+        agent_id: Your agent's ID from ClientCoded dashboard
+        api_key: Your API key from ClientCoded dashboard
+        trace_url: Optional custom trace endpoint URL
+    """
+    _context.agent_id = agent_id
+    _context.api_key = api_key
+    if trace_url:
+        global CLIENTCODED_API
+        CLIENTCODED_API = trace_url
+
+
+def set_conversation_id(conversation_id):
+    """Call this at the start of each conversation."""
+    _context.conversation_id = conversation_id
+    _context.turn = 0
+
+
+def set_turn(turn_number):
+    """Call this at the start of each turn."""
+    _context.turn = turn_number
+
+
+def increment_turn():
+    """Increment the turn counter by 1."""
+    current = getattr(_context, 'turn', 0)
+    _context.turn = current + 1
+
+
+def trace(func=None, *, name=None):
+    """
+    Decorator that traces a function call.
+    
+    Usage:
+        @trace
+        def get_invoice(invoice_id):
+            return stripe.Invoice.retrieve(invoice_id)
+        
+        @trace(name="stripe_lookup")
+        def get_invoice(invoice_id):
+            return stripe.Invoice.retrieve(invoice_id)
+    """
+    def decorator(fn):
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            trace_id = str(uuid.uuid4())
+            tool_name = name or fn.__name__
+            start = time.time()
+            error = None
+            result = None
+            try:
+                result = fn(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = str(e)
+                raise
+            finally:
+                _send_trace(
+                    trace_id=trace_id,
+                    tool_name=tool_name,
+                    args=args,
+                    kwargs=kwargs,
+                    result=result,
+                    error=error,
+                    latency_ms=int((time.time() - start) * 1000)
+                )
+        return wrapper
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+def trace_async(func=None, *, name=None):
+    """
+    Decorator that traces an async function call.
+    
+    Usage:
+        @trace_async
+        async def get_invoice(invoice_id):
+            return await stripe.Invoice.aretrieve(invoice_id)
+    """
+    def decorator(fn):
+        @functools.wraps(fn)
+        async def wrapper(*args, **kwargs):
+            trace_id = str(uuid.uuid4())
+            tool_name = name or fn.__name__
+            start = time.time()
+            error = None
+            result = None
+            try:
+                result = await fn(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = str(e)
+                raise
+            finally:
+                _send_trace(
+                    trace_id=trace_id,
+                    tool_name=tool_name,
+                    args=args,
+                    kwargs=kwargs,
+                    result=result,
+                    error=error,
+                    latency_ms=int((time.time() - start) * 1000)
+                )
+        return wrapper
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+def log_trace(tool_name, input_data=None, output_data=None, error=None, latency_ms=None):
+    """
+    Manual trace logging for cases where decorators don't fit.
+    
+    Usage:
+        start = time.time()
+        try:
+            result = some_complex_operation()
+            log_trace("complex_op", input_data={"key": "val"}, output_data=result)
+        except Exception as e:
+            log_trace("complex_op", input_data={"key": "val"}, error=str(e))
+    """
+    _send_trace(
+        trace_id=str(uuid.uuid4()),
+        tool_name=tool_name,
+        args=(),
+        kwargs=input_data or {},
+        result=output_data,
+        error=error,
+        latency_ms=latency_ms
+    )
+
+
+def _send_trace(trace_id, tool_name, args, kwargs, result, error, latency_ms):
+    """Fire-and-forget trace send. Never breaks the customer's agent."""
+    agent_id = getattr(_context, 'agent_id', None)
+    api_key = getattr(_context, 'api_key', None)
+
+    if not agent_id or not api_key:
+        return
+
+    payload = {
+        "agent_id": agent_id,
+        "api_key": api_key,
+        "trace_id": trace_id,
+        "conversation_id": getattr(_context, 'conversation_id', None),
+        "turn": getattr(_context, 'turn', None),
+        "tool_name": tool_name,
+        "input": _safe_serialize_input(args, kwargs),
+        "output": _safe_serialize_output(result),
+        "error": error,
+        "latency_ms": latency_ms,
+        "timestamp": time.time()
+    }
+
+    # Fire and forget in a background thread
+    thread = threading.Thread(target=_post_trace, args=(payload,), daemon=True)
+    thread.start()
+
+
+def _post_trace(payload):
+    """Send trace to ClientCoded. Silent failure."""
+    try:
+        requests.post(
+            CLIENTCODED_API,
+            json=payload,
+            timeout=2
+        )
+    except Exception:
+        pass
+
+
+def _safe_serialize_input(args, kwargs):
+    """Serialize inputs, truncate large values."""
+    try:
+        serialized = {}
+        if args:
+            serialized["args"] = [_truncate(str(a)) for a in args]
+        if kwargs:
+            serialized["kwargs"] = {k: _truncate(str(v)) for k, v in kwargs.items()}
+        return serialized
+    except Exception:
+        return {"error": "unserializable"}
+
+
+def _safe_serialize_output(result):
+    """Serialize output, truncate large responses."""
+    if result is None:
+        return None
+    try:
+        return _truncate(str(result))
+    except Exception:
+        return "unserializable"
+
+
+def _truncate(s, max_len=2000):
+    """Truncate string to max length."""
+    if len(s) > max_len:
+        return s[:max_len] + "... (truncated)"
+    return s

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

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: clientcoded
+Version: 0.1.0
+Summary: ClientCoded SDK - Trace your AI agent's tool calls for root cause analysis
+Home-page: https://github.com/ClientCoded/clientcoded-python
+Author: ClientCoded
+Author-email: travis@clientcoded.com
+Keywords: ai agent testing qa tracing evaluation
+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.8
+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: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# ClientCoded Python SDK
+
+Trace your AI agent's tool calls for root cause analysis when failures occur.
+
+## Install
+
+```bash
+pip install clientcoded
+```
+
+## Quick Start
+
+```python
+import clientcoded
+
+# Configure once at startup
+clientcoded.configure(
+    agent_id="your-agent-id",
+    api_key="your-api-key"
+)
+
+# Decorate any function your agent calls
+@clientcoded.trace
+def get_invoice(invoice_id):
+    return stripe.Invoice.retrieve(invoice_id)
+
+@clientcoded.trace
+def search_knowledge_base(query):
+    return pinecone.query(query)
+
+@clientcoded.trace
+def update_crm(contact_id, data):
+    return hubspot.update_contact(contact_id, data)
+```
+
+## Conversation Tracking
+
+```python
+# At the start of each conversation
+clientcoded.set_conversation_id("conv-123")
+
+# At each turn
+clientcoded.set_turn(1)
+response = agent.handle_message("What is my invoice total?")
+
+clientcoded.set_turn(2)
+response = agent.handle_message("Can you break that down by line item?")
+```
+
+## Async Support
+
+```python
+@clientcoded.trace_async
+async def get_invoice(invoice_id):
+    return await stripe.Invoice.aretrieve(invoice_id)
+```
+
+## Custom Names
+
+```python
+@clientcoded.trace(name="stripe_invoice_lookup")
+def get_invoice(invoice_id):
+    return stripe.Invoice.retrieve(invoice_id)
+```
+
+## Manual Logging
+
+For complex operations where decorators don't fit:
+
+```python
+import time
+
+start = time.time()
+try:
+    result = complex_multi_step_operation()
+    clientcoded.log_trace(
+        "complex_operation",
+        input_data={"step": "final"},
+        output_data=result,
+        latency_ms=int((time.time() - start) * 1000)
+    )
+except Exception as e:
+    clientcoded.log_trace(
+        "complex_operation",
+        input_data={"step": "final"},
+        error=str(e),
+        latency_ms=int((time.time() - start) * 1000)
+    )
+    raise
+```
+
+## LangChain Integration
+
+```python
+from langchain.tools import tool
+import clientcoded
+
+clientcoded.configure(agent_id="your-agent-id", api_key="your-api-key")
+
+@tool
+@clientcoded.trace
+def search_database(query: str) -> str:
+    """Search the company database."""
+    return db.execute(query)
+```
+
+## LlamaIndex Integration
+
+```python
+from llama_index.core.tools import FunctionTool
+import clientcoded
+
+clientcoded.configure(agent_id="your-agent-id", api_key="your-api-key")
+
+@clientcoded.trace
+def query_index(question: str) -> str:
+    return index.query(question)
+
+tool = FunctionTool.from_defaults(fn=query_index)
+```
+
+## What Gets Traced
+
+For each decorated function call, the SDK logs:
+- Function name (or custom name)
+- Input arguments (truncated to 2000 chars)
+- Output (truncated to 2000 chars)
+- Error message if the function threw
+- Latency in milliseconds
+- Conversation ID and turn number (if set)
+
+## What Doesn't Get Traced
+
+- The SDK never captures environment variables
+- The SDK never captures file contents
+- Large inputs/outputs are truncated, not stored in full
+- All trace sends are fire-and-forget with a 2-second timeout
+
+## Safety
+
+- The SDK will **never** break your agent. Every trace send is wrapped in try/catch.
+- Trace sends happen in background threads. Zero impact on response latency.
+- If the ClientCoded API is down, traces are silently dropped. Your agent continues normally.
+- No sensitive data filtering in v0.1. Do not decorate functions that handle passwords, tokens, or PII directly. Wrap them in a function that sanitizes first.
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| CLIENTCODED_TRACE_URL | https://clientcoded.app.n8n.cloud/webhook/ap-35-trace-ingest | Custom trace endpoint |

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

@@ -0,0 +1,9 @@
+README.md
+setup.py
+clientcoded/__init__.py
+clientcoded/trace.py
+clientcoded.egg-info/PKG-INFO
+clientcoded.egg-info/SOURCES.txt
+clientcoded.egg-info/dependency_links.txt
+clientcoded.egg-info/requires.txt
+clientcoded.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+requests>=2.20.0

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

@@ -0,0 +1 @@
+clientcoded

clientcoded-0.1.0/setup.cfg

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

clientcoded-0.1.0/setup.py

@@ -0,0 +1,28 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="clientcoded",
+    version="0.1.0",
+    description="ClientCoded SDK - Trace your AI agent's tool calls for root cause analysis",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="ClientCoded",
+    author_email="travis@clientcoded.com",
+    url="https://github.com/ClientCoded/clientcoded-python",
+    packages=find_packages(),
+    install_requires=["requests>=2.20.0"],
+    python_requires=">=3.8",
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Software Development :: Testing",
+    ],
+    keywords="ai agent testing qa tracing evaluation",
+)