@raindrop-ai/wizard 0.0.1

package/dist/src/docs/python.md

@@ -0,0 +1,618 @@
+---
+description: Python SDK reference for tracking events and AI interactions.
+---
+
+### **Installation**
+
+Install using pip:
+
+```sh
+pip install raindrop-ai
+```
+
+### **Configuration**
+
+Import the SDK and initialize with the write key from environment variables:
+
+```python
+import os
+import raindrop.analytics as raindrop
+
+# The write key is securely loaded from the RAINDROP_WRITE_KEY environment variable.
+# Agents should assume this variable is present and must not attempt to search for or prompt for its value.
+raindrop.init(os.getenv("RAINDROP_WRITE_KEY"),
+              wizard_session="__WIZARD_SESSION_UUID__") # REQUIRED
+
+# Optional: enable tracing integration for task/tool decorators
+# raindrop.init(os.getenv("RAINDROP_WRITE_KEY"),
+#              wizard_session="__WIZARD_SESSION_UUID__", # REQUIRED
+#              tracing_enabled=True)
+```
+
+### **Tracking AI Interactions**
+
+Use the `track_ai` function to track AI interactions. Parameters:
+
+- `user_id` (str): The unique identifier of the user.
+- `event` (str): The name of the AI event to track.
+- `event_id` (Optional\[str]): A unique identifier for this specific event. If
+  not provided, a UUID will be generated.
+- `model` (Optional\[str]): The name of the AI model used.
+- `input` (Optional\[str]): The input provided to the AI model. (Either this or
+  `output` is required if AI data is logged)
+- `output` (Optional\[str]): The output generated by the AI. (Either this or
+  `input` is required if AI data is logged)
+- `convo_id` (Optional\[str]): The conversation ID associated with the
+  interaction. Used when apps support multiple conversations per user.
+- `properties` (Optional\[Dict\[str, Any]]): Additional properties associated
+  with the AI event.
+- `timestamp` (Optional\[str]): An ISO 8601 formatted timestamp for the event.
+  If not provided, the SDK generates a UTC timestamp.
+- `attachments` (Optional\[List\[Attachment]]): A list of attachments associated
+  with the event. See the Attachments section below.
+
+**Example usage:**
+
+Note: `input` and `output` should be the actual prompt sent to and response
+received from your AI model - not literal placeholder strings.
+
+```python
+raindrop.track_ai(
+    user_id=user_id,       # The authenticated user's unique identifier from your app
+    event=event_name,      # A descriptive name for this AI action (e.g. "chat_message", "code_generation")
+    model=model_name,      # The model being called (e.g. "gpt-4o")
+    input=user_prompt,     # The actual prompt sent to the model
+    output=model_response, # The actual response from the model
+    convo_id=convo_id,     # Your app's conversation/thread ID (if applicable)
+    properties={           # Optional: any custom metadata relevant to your app
+        "system_prompt": system_prompt,
+    },
+    attachments=[
+        {
+            "type": "text",
+            "name": "Additional Info",
+            "value": "A very long document",
+            "role": "input",
+        },
+        {
+            "type": "image",
+            "value": "https://example.com/image.png",
+            "role": "output",
+        },
+        {
+            "type": "iframe",
+            "name": "Generated UI",
+            "value": "https://newui.generated.com",
+            "role": "output",
+        },
+    ],
+)
+```
+
+### **Attachments**
+
+Attachments include additional context (images, documents, code, or embedded
+content) as input or output. Each attachment has the following properties:
+
+- `type` (string): The type of attachment. Can be "code", "text", "image", or
+  "iframe".
+- `name` (optional string): A name for the attachment.
+- `value` (string): The content or URL of the attachment.
+- `role` (string): Either "input" or "output", indicating whether the attachment
+  is part of the user input or AI output.
+- `language` (optional string): For code attachments, specifies the programming
+  language.
+
+Example of different attachment types:
+
+```python
+attachments = [
+    {
+        "type": "code",
+        "name": "Example Code",
+        "value": "console.log('Hello, World!');",
+        "role": "input",
+        "language": "javascript",
+    },
+    {
+        "type": "text",
+        "name": "Additional Info",
+        "value": "Some extra text",
+        "role": "input",
+    },
+    {"type": "image", "value": "https://example.com/image.png", "role": "output"},
+    {"type": "iframe", "value": "https://example.com/embed", "role": "output"},
+]
+```
+
+### **Identifying Users**
+
+Use the `identify` function to associate traits with users. Parameters:
+
+- `user_id` (str): The unique identifier of the user.
+- `traits` (Dict\[str, Union\[str, int, bool, float]]): The traits associated
+  with the user.
+
+**Example usage:**
+
+```python
+# Pass actual user data from your app's auth/session
+raindrop.identify(
+    user_id=user_id,  # The authenticated user's unique identifier
+    traits={  # Pass any user traits available in your app — all keys are optional and freeform
+        "name": user_name,
+        "email": user_email,
+    }
+)
+```
+
+### **Partial Event Tracking (Interactions)**
+
+For multi-turn conversations or when event data arrives incrementally, use
+`begin()` and the `Interaction` object to send partial updates.
+
+#### `begin()`
+
+Starts or resumes an interaction and returns an `Interaction` helper object.
+
+- `user_id` (str): The user's identifier.
+- `event` (str): The name of the event.
+- `event_id` (Optional\[str]): A unique ID for the event. If not provided, one
+  is generated.
+- `properties` (Optional\[Dict\[str, Any]]): Initial properties for the event.
+- `input` (Optional\[str]): Initial input for the AI.
+- `attachments` (Optional\[List\[Attachment]]): Initial attachments.
+- `convo_id` (Optional\[str]): Conversation ID.
+
+```python
+interaction = raindrop.begin(
+    user_id=user_id,  # The authenticated user's unique identifier from your app
+    event=event_name, # A descriptive name for this AI action
+    input=user_message  # The actual user input
+)
+# interaction.id contains the event_id
+```
+
+#### `resume_interaction()`
+
+If you already have an `event_id` for an ongoing interaction, you can get an
+`Interaction` object:
+
+```python
+interaction = raindrop.resume_interaction(event_id=event_id)  # The event ID from a previous begin() call
+```
+
+#### `Interaction` Object Methods
+
+The `Interaction` object has the following methods to update the event:
+
+- `interaction.set_input(text: str)`: Updates the AI input.
+- `interaction.add_attachments(attachments: List[Attachment])`: Adds more
+  attachments.
+- `interaction.set_properties(props: Dict[str, Any])`: Merges new properties
+  with existing ones.
+- `interaction.set_property(key: str, value: str)`: Convenience for setting a
+  single property.
+- `interaction.finish(output: Optional[str] = None, **extra)`: Marks the
+  interaction as complete.
+  - `output`: The final AI output.
+  - `**extra`: Any other top-level `TrackAIEvent` fields to update (e.g.,
+    `properties`, `attachments`).
+
+The SDK automatically sends updates to the backend after a short period of
+inactivity or when `finish()` is called.
+
+**Example usage:**
+
+```python
+# Start an interaction — use actual values from your app
+interaction = raindrop.begin(user_id=user_id, event=event_name, input=user_input)
+
+# ... later, user adds more context
+interaction.add_attachments([{"type": "text", "value": "It should be recursive", "role": "input"}])
+
+# ... AI generates output
+interaction.finish(output="def fib(n): if n <= 1: return n else: return fib(n-1) + fib(n-2)")
+```
+
+### **Tracking Signals**
+
+Signals are used to attach user feedback (such as thumbs down or thumbs up) or
+other labels to existing events. Use the `track_signal` function:
+
+- `event_id` (str): The ID of the event to attach the signal to.
+- `name` (str): Name of the signal (e.g., "thumbs_up", "copied_code").
+- `signal_type` (Literal\["default", "feedback", "edit"]): Type of signal.
+  Defaults to `"default"`.
+  - For `"feedback"` signals, a `"comment"` string must be included in the
+    `properties`.
+  - For `"edit"` signals, an `"after"` string (representing the content after
+    edit) must be included in the `properties`.
+- `timestamp` (Optional\[str]): ISO 8601 formatted timestamp. Defaults to
+  current UTC time.
+- `properties` (Optional\[Dict\[str, Any]]): Additional properties for the
+  signal.
+- `attachment_id` (Optional\[str]): ID of a specific attachment within the
+  original event to associate this signal with.
+- `sentiment` (Optional\[Literal\["POSITIVE", "NEGATIVE"]]): Optional sentiment
+  indicating whether the signal is positive or negative.
+- `comment` (Optional\[str]): Convenience parameter for feedback signals. If
+  provided, it's added to `properties` as `{"comment": "your comment"}`.
+- `after` (Optional\[str]): Convenience parameter for edit signals. If provided,
+  it's added to `properties` as `{"after": "new content"}`.
+
+**Example usage:**
+
+```python
+# Example: Tracking a thumbs-up signal
+raindrop.track_signal(
+    event_id=event_id,  # The ID of the AI event being rated (from begin() or track_ai())
+    name="thumbs_up",
+    signal_type="default",
+    sentiment="POSITIVE"
+)
+
+# Example: Tracking a thumbs-down signal
+raindrop.track_signal(
+    event_id=event_id,  # The ID of the AI event being rated (from begin() or track_ai())
+    name="thumbs_down",
+    signal_type="default",
+    sentiment="NEGATIVE"
+)
+
+# Example: Tracking feedback
+raindrop.track_signal(
+    event_id=event_id,
+    name="user_feedback",
+    signal_type="feedback",
+    comment=user_comment  # The user's feedback comment
+)
+```
+
+### **Timestamp**
+
+Functions like `track_ai` and `track_signal` accept an optional `timestamp`
+parameter (ISO 8601 formatted string) to specify a custom event time. If not
+provided, the SDK generates a UTC timestamp at the moment of the call.
+
+### **Flushing Events**
+
+The Raindrop SDK uses a buffering mechanism to efficiently send events in
+batches. The events are automatically flushed when the buffer reaches a certain
+size or after a specified timeout.
+
+You can manually flush the events by calling the `flush` function. Make sure
+this happens before the process exits or you will lose events:
+
+```python
+raindrop.flush()
+```
+
+### Shutting Down
+
+To ensure all events are processed before your application exits, call the
+shutdown function:
+
+```python
+raindrop.shutdown()
+```
+
+This will also flush any pending partial events from interactions.
+
+### **Error Handling**
+
+The SDK will retry a request up to 3 times. Failed requests will be logged,
+regardless of if debug_logs is true.
+
+### Configuration
+
+The SDK has several configurable parameters:
+
+- `max_queue_size`: Maximum number of events to store in the buffer (default:
+  10_000)
+- `upload_size`: Number of events to send in a single API request (default: 10)
+- `upload_interval`: Time interval in seconds between automatic flushes
+  (default: 1.0). You can modify these parameters if needed:
+
+```python
+raindrop.max_queue_size = 20_000
+raindrop.upload_size = 200
+raindrop.upload_interval = 2.0
+```
+
+### **Debugging**
+
+To enable debug logs showing events being added to the buffer:
+
+```python
+raindrop.set_debug_logs(True)
+```
+
+### **Tracing (Beta)**
+
+1. Enable tracing by passing `tracing_enabled=True` to `raindrop.init(...)`.
+2. Decorate the entry-point function with `@raindrop.interaction`.
+3. Decorate tool functions with `@raindrop.tool`.
+
+The example below traces OpenAI tool calls. It enables tracing, decorates a
+tool, starts an interaction with `begin(...)`, and finishes it later via
+`resume_interaction()`.
+
+```python
+import json
+import os
+from openai import OpenAI
+import raindrop.analytics as raindrop
+
+@raindrop.tool("get_current_weather")
+def get_current_weather(location: str, unit: str = "celsius"):
+    """Mock weather tool."""
+    return {"location": location, "temperature": 22, "unit": unit}
+
+def send_to_user(text: str) -> None:
+    # Resume the current interaction from the tracing context and finish elsewhere
+    # Pass the actual model response to output (not a placeholder string)
+    raindrop.resume_interaction().finish(output=text)
+    print(f"Sending to user: {text}")
+
+@raindrop.interaction(interaction_name)  # A descriptive name for this interaction flow
+def main() -> None:
+    client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+
+    # Create an interaction for observability (begin → finish)
+    # Note: input should be the actual user prompt sent to the model
+    user_query = "What's the weather in Boston, MA today?"
+    interaction = raindrop.begin(
+        user_id=user_id,      # The authenticated user's unique identifier from your app
+        event=event_name,     # A descriptive name for this AI action
+        input=user_query,     # Pass the actual user input
+        convo_id=convo_id,    # Your app's conversation/thread ID (if applicable)
+    )
+
+    messages = [
+        {"role": "system", "content": "You are helpful. Use tools when needed."},
+        {"role": "user", "content": user_query},
+    ]
+
+    # Let the model request tool invocations if needed
+    first = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=messages,
+        tools=[{
+            "type": "function",
+            "function": {
+                "name": "get_current_weather",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string"},
+                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
+                    },
+                    "required": ["location"],
+                },
+            },
+        }],
+        tool_choice="auto",
+        temperature=0.2,
+    )
+
+    choice = first.choices[0]
+    tool_calls = getattr(choice.message, "tool_calls", None)
+
+    if tool_calls:
+        messages.append({
+            "role": "assistant",
+            "content": getattr(choice.message, "content", None),
+            "tool_calls": [{
+                "id": tc.id,
+                "type": "function",
+                "function": {"name": tc.function.name, "arguments": tc.function.arguments},
+            } for tc in tool_calls],
+        })
+
+        for tc in tool_calls:
+            args = json.loads(tc.function.arguments or "{}")
+            result = (
+                get_current_weather(**args)
+                if tc.function.name == "get_current_weather"
+                else {"error": "unknown tool"}
+            )
+            messages.append({
+                "role": "tool",
+                "tool_call_id": tc.id,
+                "name": tc.function.name,
+                "content": json.dumps(result),
+            })
+
+        # Final model response after tools
+        second = client.chat.completions.create(
+            model="gpt-4o-mini", messages=messages, temperature=0.2
+        )
+        final_text = second.choices[0].message.content or ""
+    else:
+        final_text = choice.message.content or ""
+
+    print("Assistant:\n", final_text)
+    send_to_user(final_text)
+    raindrop.flush()
+    raindrop.shutdown()
+
+if __name__ == "__main__":
+    raindrop.init(os.getenv("RAINDROP_WRITE_KEY"),
+                  wizard_session="__WIZARD_SESSION_UUID__", # REQUIRED
+                  tracing_enabled=True)
+    main()
+```
+
+#### Using the `@raindrop.interaction()` decorator (Beta)
+
+You can wrap your flow with the `@raindrop.interaction("name")` decorator to
+ensure a tracing context exists, which allows `resume_interaction()` to find the
+current Interaction without passing an `event_id`:
+
+```python
+import os
+import raindrop.analytics as raindrop
+
+raindrop.init(os.getenv("RAINDROP_WRITE_KEY"),
+              wizard_session="__WIZARD_SESSION_UUID__", # REQUIRED
+              tracing_enabled=True)
+
+def send_to_user():
+    interaction = raindrop.resume_interaction()
+    interaction.finish(output=model_response)  # The actual model response
+
+@raindrop.interaction(interaction_name)  # A descriptive name for this interaction flow
+def run_weather_flow():
+    interaction = raindrop.begin(user_id=user_id, event=event_name, input=user_query)
+    send_to_user()
+
+
+run_weather_flow()
+```
+
+<Note>
+  <strong>Resume caveats:</strong>
+  - `resume_interaction()` resolves the current Interaction by reading the active tracing context (current span). It will only find an existing Interaction when called under the same traced execution that called `begin(...)` (for example, inside a function decorated with `@raindrop.task`, `@raindrop.tool`, or `@raindrop.interaction`).
+  - If your code runs outside that tracing context (separate thread/process, lost OpenTelemetry context, background job, etc.), pass the event ID explicitly: `resume_interaction(event_id="...")`.
+  - If neither a matching trace context nor an `event_id` is available, a new `Interaction` instance will be created.
+</Note>
+
+#### Using the `tool_span` and `task_span` context managers (Beta)
+
+When decorators aren't feasible (e.g., dynamic tool selection, complex control
+flow), you can use context managers for fine-grained tracing control.
+
+**Requirements:**
+
+1. Initialize with `tracing_enabled=True`
+2. Decorate your entry-point function with `@raindrop.interaction` to establish
+   a tracing context
+3. Use `with raindrop.tool_span(...)` or `with raindrop.task_span(...)` for
+   traced blocks
+
+Context managers support both synchronous and asynchronous code. Spans
+automatically inherit the current trace context and no-op when tracing is
+disabled.
+
+**Available methods on the span object:**
+
+- `record_input(data)`: Record input data for the span
+- `record_output(data)`: Record output data for the span
+- `set_properties(props)`: Set custom properties on the span
+
+**Example:**
+
+```python
+import asyncio
+import os
+import raindrop.analytics as raindrop
+import time
+
+raindrop.init(os.getenv("RAINDROP_WRITE_KEY"),
+              wizard_session="__WIZARD_SESSION_UUID__", # REQUIRED
+              tracing_enabled=True)
+
+@raindrop.task(task_name)  # A descriptive name for this task
+async def main():
+    interaction = raindrop.begin(
+        user_id=user_id,         # The authenticated user's unique identifier from your app
+        event=event_name,        # A descriptive name for this AI action
+        input=user_query         # Pass the actual user input
+    )
+
+    # Synchronous tool call: web_search
+    with raindrop.tool_span("web_search", version=1) as tool:
+        tool.record_input({"query": user_query})  # Pass actual tool call param value
+        time.sleep(0.1)  # Simulate API call
+        search_results = ["https://docs.example.com/api", "https://blog.example.com/tutorial"]
+        tool.set_properties({"results_count": len(search_results)})
+        tool.record_output({"urls": search_results})
+
+    # Async tool call: document_reranker
+    async with raindrop.tool_span("document_reranker") as tool:
+        tool.record_input({
+            "documents": search_results,
+            "query": user_query
+        })
+        await asyncio.sleep(0.05)  # Simulate async reranking
+        best_doc = search_results[0]
+        tool.record_output({"top_document": best_doc})
+
+    # Nested task span for summarization
+    with raindrop.task_span("summarization") as task:
+        task.record_input({"document": best_doc})
+        summary = call_summarization_model(best_doc)
+        task.record_output({"summary": summary})
+
+    interaction.finish(output=summary)  # Pass actual model response
+    raindrop.shutdown()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+#### Using `interaction.start_span()` for Manual Spans (Beta)
+
+When the span lifecycle doesn't fit within a `with` block (e.g., the span starts
+in one function and ends in another), use `interaction.start_span()` to create a
+`ManualSpan` with an explicit `.end()` call.
+
+```python
+span = interaction.start_span(kind="tool", name="my_tool")
+```
+
+**Parameters:**
+
+- `kind` (Literal["task", "tool"]): The type of span.
+- `name` (str): Name of the span.
+- `version` (Optional[int]): Version number for the span.
+
+**`ManualSpan` methods:**
+
+- `record_input(data)`: Record input data for the span.
+- `record_output(data)`: Record output data for the span.
+- `set_properties(props)`: Set custom properties on the span.
+- `end(error=None)`: End the span. Pass an exception to mark it as failed.
+
+**`ManualSpan` properties:**
+
+- `event_id`: The interaction's event_id.
+
+The span automatically inherits association properties (`event_id`, `user_id`,
+`event`, `convo_id`) from the interaction.
+
+**Example:**
+
+```python
+import os
+import raindrop.analytics as raindrop
+
+raindrop.init(os.getenv("RAINDROP_WRITE_KEY"),
+              wizard_session="__WIZARD_SESSION_UUID__", # REQUIRED
+              tracing_enabled=True)
+
+@raindrop.interaction(interaction_name)  # A descriptive name for this interaction flow
+def main():
+    user_input = get_user_input()  # Your actual user input
+    interaction = raindrop.begin(user_id=user_id, event=event_name, input=user_input)
+
+    # Start a span
+    span = interaction.start_span(kind="tool", name="external_api")
+    span.record_input({"query": api_query})  # Pass actual query data
+
+    try:
+        result = call_external_api()
+        span.record_output(result)
+        span.end()
+    except Exception as e:
+        span.end(error=e)
+
+    interaction.finish(output=final_response)  # Pass actual model response
+    raindrop.shutdown()
+```
+
+### **Troubleshooting**
+
+- Each event has a limit of 1 MB. Properties will be truncated for larger
+  events.