Update Python SDK documentation and clean up codebase

agentops/__init__.py

@@ -64,7 +64,6 @@ def record(event):
     """
     from agentops.helpers.time import get_ISO_time
 
-    # TODO: Manual timestamp assignment is a temporary fix; should use proper event lifecycle
     if event and hasattr(event, "end_timestamp"):
         event.end_timestamp = get_ISO_time()
 

agentops/helpers/system.py

@@ -77,7 +77,6 @@ def get_sys_packages():
 def get_installed_packages():
     try:
         return {
-            # TODO: add to opt out
             "Installed Packages": {
                 dist.metadata.get("Name"): dist.metadata.get("Version") for dist in importlib.metadata.distributions()
             }

agentops/legacy/__init__.py

@@ -213,7 +213,7 @@ def ToolEvent(*args: Any, **kwargs: Any) -> None:
 
 @deprecated("Automatically tracked in v4.")
 def ErrorEvent(*args: Any, **kwargs: Any) -> Any:
-    """@deprecated Automatically tracked in v4. Returns minimal object for test compatibility."""
+    """@deprecated Automatically tracked in v4."""
     from agentops.helpers.time import get_ISO_time
 
     class LegacyErrorEvent:
@@ -226,7 +226,7 @@ def __init__(self):
 
 @deprecated("Automatically tracked in v4.")
 def ActionEvent(*args: Any, **kwargs: Any) -> Any:
-    """@deprecated Automatically tracked in v4. Returns minimal object for test compatibility."""
+    """@deprecated Automatically tracked in v4."""
     from agentops.helpers.time import get_ISO_time
 
     class LegacyActionEvent:

agentops/sdk/exporters.py

@@ -30,10 +30,6 @@ def __init__(
         compression: Optional[Compression] = None,
         **kwargs,
     ):
-        # TODO: Implement re-authentication
-        # FIXME: endpoint here is not "endpoint" from config
-        # self._session = HttpClient.get_authenticated_session(endpoint, api_key)
-
         # Initialize the parent class
         super().__init__(
             endpoint=endpoint,

docs/mint.json

@@ -179,6 +179,7 @@
         "v2/usage/dashboard-info",
         "v2/usage/sdk-reference",
         "v2/usage/typescript-sdk",
+        "v2/usage/typescript-sdk-reference",
         "v2/usage/mcp-server",
         "v2/usage/advanced-configuration",
         "v2/usage/context-managers",

docs/v2/usage/sdk-reference.mdx

@@ -8,7 +8,7 @@ description: "All functions and classes exposed in the top layer of the SDK"
 This reference documents the functions and classes available with `import agentops` for the Python SDK. The AgentOps SDK is designed for easy integration with your agent applications, offering both simple auto-instrumentation and more detailed manual tracing capabilities.
 
 <Note>
-This documentation covers the Python SDK. A TypeScript/JavaScript SDK is also available - see our [TypeScript SDK guide](/v2/usage/typescript-sdk) for details.
+This documentation covers the Python SDK. For TypeScript/JavaScript applications, see our [TypeScript SDK guide](/v2/usage/typescript-sdk) and [TypeScript SDK Reference](/v2/usage/typescript-sdk-reference).
 </Note>
 
 ## Core Functions
@@ -25,6 +25,7 @@ Initializes the AgentOps SDK and automatically starts tracking your application.
 - `endpoint` (str, optional): The endpoint for the AgentOps service. If not provided, will be read from the `AGENTOPS_API_ENDPOINT` environment variable. Defaults to 'https://api.agentops.ai'.
 - `app_url` (str, optional): The dashboard URL for the AgentOps app. If not provided, will be read from the `AGENTOPS_APP_URL` environment variable. Defaults to 'https://app.agentops.ai'.
 - `max_wait_time` (int, optional): The maximum time to wait in milliseconds before flushing the queue. Defaults to 5,000 (5 seconds).
+- `export_flush_interval` (int, optional): Time interval in milliseconds between automatic exports of telemetry data. Defaults to 1000.
 - `max_queue_size` (int, optional): The maximum size of the event queue. Defaults to 512.
 - `default_tags` (List[str], optional): Default tags for the sessions that can be used for grouping or sorting later (e.g. ["GPT-4"]).
 - `tags` (List[str], optional): **[Deprecated]** Use `default_tags` instead. Will be removed in v4.0.
@@ -65,6 +66,7 @@ Updates client configuration after initialization. Supports the same parameters
 - `endpoint` (str, optional): The endpoint for the AgentOps service.
 - `app_url` (str, optional): The dashboard URL for the AgentOps app.
 - `max_wait_time` (int, optional): Maximum time to wait in milliseconds before flushing the queue.
+- `export_flush_interval` (int, optional): Time interval in milliseconds between automatic exports of telemetry data.
 - `max_queue_size` (int, optional): Maximum size of the event queue.
 - `default_tags` (List[str], optional): Default tags for the sessions.
 - `instrument_llm_calls` (bool, optional): Whether to instrument LLM calls.

docs/v2/usage/typescript-sdk-reference.mdx

@@ -0,0 +1,184 @@
+---
+title: "TypeScript SDK Reference"
+description: "Complete API reference for the AgentOps TypeScript SDK"
+---
+
+# TypeScript SDK Reference
+
+This reference documents the classes, interfaces, and functions available in the AgentOps TypeScript SDK. The SDK provides automatic instrumentation for AI agent frameworks with OpenTelemetry standards compliance.
+
+## Core Classes
+
+### `Client`
+
+The main SDK client class that handles initialization, configuration, and instrumentation management.
+
+#### `init(config?: Partial<Config>): Promise<void>`
+
+Initializes the AgentOps SDK with OpenTelemetry instrumentation.
+
+**Parameters**:
+- `config` (Partial<Config>, optional): Configuration object to override defaults
+
+**Configuration Options**:
+- `apiKey` (string, optional): API Key for AgentOps services. If not provided, reads from `AGENTOPS_API_KEY` environment variable
+- `apiEndpoint` (string, optional): The endpoint for the AgentOps service. Defaults to 'https://api.agentops.ai'
+- `otlpEndpoint` (string, optional): OpenTelemetry endpoint. Defaults to 'https://otlp.agentops.ai'
+- `serviceName` (string, optional): Service name for telemetry. Defaults to 'agentops'
+- `logLevel` (LogLevel, optional): Log level ('debug' | 'info' | 'error'). Defaults to 'error'
+
+**Throws**: Error when API key is not provided via config or environment variable
+
+**Example**:
+```typescript
+import { agentops } from 'agentops';
+
+// Initialize with environment variable
+await agentops.init();
+
+// Initialize with custom configuration
+await agentops.init({
+  apiKey: 'your-api-key',
+  logLevel: 'debug'
+});
+```
+
+#### `initialized: boolean`
+
+Read-only property that returns true if the SDK has been successfully initialized.
+
+#### `shutdown(): Promise<void>`
+
+Shuts down the OpenTelemetry SDK and cleans up resources. Called automatically on process exit.
+
+## Interfaces
+
+### `Config`
+
+Configuration interface for the AgentOps client.
+
+```typescript
+interface Config {
+  apiEndpoint?: string;
+  otlpEndpoint?: string;
+  serviceName?: string;
+  apiKey?: string;
+  logLevel?: LogLevel;
+}
+```
+
+### `InstrumentorMetadata`
+
+Metadata interface for instrumentors.
+
+```typescript
+interface InstrumentorMetadata {
+  name: string;
+  version: string;
+  description: string;
+  targetLibrary: string;
+  targetVersions: string[];
+}
+```
+
+## Types
+
+### `LogLevel`
+
+```typescript
+type LogLevel = 'debug' | 'info' | 'error';
+```
+
+## Instrumentation
+
+### `InstrumentationBase`
+
+Abstract base class for creating custom instrumentors.
+
+**Example**:
+```typescript
+import { InstrumentationBase } from 'agentops';
+
+export class MyInstrumentation extends InstrumentationBase {
+  static readonly metadata: InstrumentorMetadata = {
+    name: 'my-instrumentation',
+    version: '1.0.0',
+    description: 'Custom instrumentation',
+    targetLibrary: 'my-library',
+    targetVersions: ['>=1.0.0']
+  };
+
+  protected setup(moduleExports: any): any {
+    // Instrumentation logic
+    return moduleExports;
+  }
+}
+```
+
+## Utility Functions
+
+### `getPackageVersion(): string`
+
+Returns the version of the AgentOps SDK package.
+
+### `safeSerialize(value: any): string`
+
+Safely serializes a value to JSON string, handling circular references.
+
+### `extractAttributesFromMapping(data: any, mapping: AttributeMap): AttributeMap`
+
+Extracts attributes from data using a mapping configuration.
+
+## Semantic Conventions
+
+The SDK exports semantic convention constants for consistent attribute naming:
+
+### Agent Attributes
+- `AGENT_NAME`: 'agent.name'
+- `AGENT_TYPE`: 'agent.type'
+- `AGENT_VERSION`: 'agent.version'
+- `AGENT_ID`: 'agent.id'
+
+### GenAI Attributes
+- `GEN_AI_REQUEST_MODEL`: 'gen_ai.request.model'
+- `GEN_AI_REQUEST_MAX_TOKENS`: 'gen_ai.request.max_tokens'
+- `GEN_AI_USAGE_INPUT_TOKENS`: 'gen_ai.usage.prompt_tokens'
+- `GEN_AI_USAGE_OUTPUT_TOKENS`: 'gen_ai.usage.completion_tokens'
+
+## Framework Support
+
+### OpenAI Agents
+
+The SDK provides first-class support for the OpenAI Agents framework with automatic instrumentation of:
+
+- Agent lifecycle events
+- LLM generation calls
+- Function/tool calls
+- Audio processing
+- Agent handoffs
+- Custom events
+
+Simply initialize AgentOps before using the OpenAI Agents SDK:
+
+```typescript
+import { agentops } from 'agentops';
+import { Agent, run } from '@openai/agents';
+
+await agentops.init();
+
+const agent = new Agent({
+  name: 'My Assistant',
+  instructions: 'You are a helpful assistant.',
+  tools: [/* your tools */],
+});
+
+const result = await run(agent, "Hello!");
+```
+
+## Debug Logging
+
+Enable detailed instrumentation logs:
+
+```bash
+DEBUG=agentops:* node your-app.js
+```

docs/v2/usage/typescript-sdk.mdx

@@ -11,6 +11,8 @@ AgentOps provides TypeScript/JavaScript support through two SDK options:
 
 The modern TypeScript SDK is built on OpenTelemetry standards and provides comprehensive instrumentation for AI agents.
 
+For complete API documentation, see the [TypeScript SDK Reference](/v2/usage/typescript-sdk-reference).
+
 ### Installation
 
 ```bash