logicgaze 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 LLM Tracking
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,200 @@
1
+ Metadata-Version: 2.4
2
+ Name: logicgaze
3
+ Version: 1.1.0
4
+ Summary: AI-native observability SDK for tracing, evaluating, and optimizing production LLM applications
5
+ Project-URL: Homepage, https://github.com/VikneeshVG/logicgaze
6
+ Project-URL: Repository, https://github.com/VikneeshVG/logicgaze
7
+ Project-URL: Issues, https://github.com/VikneeshVG/logicgaze/issues
8
+ Author-email: Vikneesh VG <vikneeshwaran.k@ventragate.com>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: ai,anthropic,evaluation,langchain,llm,logicgaze,observability,openai,tracing
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Requires-Python: >=3.9
24
+ Requires-Dist: httpx>=0.26.0
25
+ Provides-Extra: dev
26
+ Requires-Dist: build>=1.0.0; extra == 'dev'
27
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
28
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
29
+ Requires-Dist: twine>=4.0.0; extra == 'dev'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # llm-tracking
33
+
34
+ Python SDK for [LogicGaze](https://github.com/yourusername/tracker) — an AI-native observability platform.
35
+ All LLM calls are routed through the LogicGaze gateway, which records traces, spans, token usage, and cost automatically.
36
+
37
+ ## Installation
38
+
39
+ ```bash
40
+ pip install llm-tracking
41
+ ```
42
+
43
+ ## Quick Start
44
+
45
+ ### 1. Initialize once at startup
46
+
47
+ ```python
48
+ import llm_tracking
49
+
50
+ llm_tracking.init(
51
+ api_key="lgz_...", # LogicGaze API key (or set LLM_TRACKING_API_KEY)
52
+ base_url="http://localhost:8000", # your LogicGaze backend URL
53
+ )
54
+ ```
55
+
56
+ ### 2. Wrap your AI client
57
+
58
+ **OpenAI**
59
+ ```python
60
+ from openai import OpenAI
61
+ import llm_tracking
62
+
63
+ llm_tracking.init(api_key="lgz_...")
64
+ client = llm_tracking.wrap_openai(OpenAI())
65
+
66
+ response = client.chat.completions.create(
67
+ model="gpt-4o",
68
+ messages=[{"role": "user", "content": "Hello!"}],
69
+ )
70
+ print(response.choices[0].message.content)
71
+ ```
72
+
73
+ **Anthropic**
74
+ ```python
75
+ from anthropic import Anthropic
76
+ import llm_tracking
77
+
78
+ llm_tracking.init(api_key="lgz_...")
79
+ client = llm_tracking.wrap_anthropic(Anthropic())
80
+
81
+ response = client.messages.create(
82
+ model="claude-3-5-sonnet-20241022",
83
+ max_tokens=1024,
84
+ messages=[{"role": "user", "content": "Hello!"}],
85
+ )
86
+ print(response.content[0].text)
87
+ ```
88
+
89
+ > **Note:** The wrapped client routes calls through the LogicGaze gateway.
90
+ > The AI provider credentials must be configured in your LogicGaze backend, not in the client app.
91
+
92
+ ### 3. Group calls with `TraceContext`
93
+
94
+ ```python
95
+ from llm_tracking import TraceContext, wrap_openai
96
+ from openai import OpenAI
97
+
98
+ client = wrap_openai(OpenAI())
99
+
100
+ with TraceContext(session_id="sess-abc", user_id="user-42", service_name="chat-api"):
101
+ # Both calls share the same session in the trace viewer
102
+ client.chat.completions.create(model="gpt-4o", messages=[...])
103
+ client.chat.completions.create(model="gpt-4o", messages=[...])
104
+ ```
105
+
106
+ ### 4. Use `@traceable` on functions
107
+
108
+ ```python
109
+ from llm_tracking import traceable, wrap_openai
110
+ from openai import OpenAI
111
+
112
+ client = wrap_openai(OpenAI())
113
+
114
+ @traceable(session_id="sess-1", service_name="recommendation-engine")
115
+ def recommend(user_query: str):
116
+ return client.chat.completions.create(
117
+ model="gpt-4o",
118
+ messages=[{"role": "user", "content": user_query}],
119
+ )
120
+
121
+ # Async functions are supported too
122
+ @traceable(service_name="summarizer")
123
+ async def summarize(text: str):
124
+ return await client.chat.completions.create(
125
+ model="gpt-4o",
126
+ messages=[{"role": "user", "content": f"Summarize: {text}"}],
127
+ )
128
+ ```
129
+
130
+ ### 5. Query traces programmatically
131
+
132
+ ```python
133
+ from llm_tracking import get_client
134
+
135
+ lg = get_client()
136
+
137
+ # List recent traces
138
+ traces = lg.list_traces(service_name="chat-api", page_size=20)
139
+
140
+ # Get a specific trace with all spans
141
+ trace = lg.get_trace("trace-uuid-here", include_spans=True)
142
+
143
+ # Dashboard overview (last 24 h)
144
+ overview = lg.get_dashboard(window_hours=24)
145
+ print(overview["total_requests"], overview["total_cost_usd"])
146
+
147
+ # Estimate cost before a call
148
+ estimate = lg.estimate_cost("openai", "gpt-4o", prompt_tokens=500, completion_tokens=200)
149
+ ```
150
+
151
+ ## Configuration
152
+
153
+ | Parameter | Environment variable | Default |
154
+ |-----------|---------------------|---------|
155
+ | `api_key` | `LLM_TRACKING_API_KEY` | — |
156
+ | `base_url` | — | `http://localhost:8000` |
157
+ | `timeout` | — | `30.0` s |
158
+
159
+ ## API Reference
160
+
161
+ ### `llm_tracking.init(api_key, base_url, timeout)`
162
+ Initialize the global client. Call once at startup.
163
+
164
+ ### `wrap_openai(client, *, service_name=None)`
165
+ Patches `client.chat.completions.create` (sync & async). Returns the same client object.
166
+
167
+ ### `wrap_anthropic(client, *, service_name=None)`
168
+ Patches `client.messages.create` (sync & async). Returns the same client object.
169
+
170
+ ### `TraceContext(*, project, trace_id, session_id, user_id, service_name, tags)`
171
+ Context manager (sync & async). Sets metadata injected into every gateway call made within the block.
172
+
173
+ ### `@traceable(*, name, project, session_id, user_id, service_name, tags, run_type)`
174
+ Decorator. Wraps the function body in a `TraceContext`. Works with both sync and async functions. Can be used with or without arguments.
175
+
176
+ ### `LogicGazeClient` methods
177
+
178
+ | Method | Backend endpoint |
179
+ |--------|-----------------|
180
+ | `chat_completion(provider, model, messages, **kwargs)` | `POST /gateway/chat/completions` |
181
+ | `achat_completion(...)` | async version of above |
182
+ | `list_traces(**filters)` | `GET /traces` |
183
+ | `get_trace(trace_id, include_spans)` | `GET /traces/{id}` |
184
+ | `get_spans(trace_id)` | `GET /traces/{id}/spans` |
185
+ | `get_agent_graph(trace_id)` | `GET /traces/{id}/agent-graph` |
186
+ | `get_dashboard(window_hours)` | `GET /dashboard/overview` |
187
+ | `get_model_distribution(window_hours)` | `GET /dashboard/model-distribution` |
188
+ | `get_provider_breakdown(window_hours)` | `GET /dashboard/provider-breakdown` |
189
+ | `estimate_cost(provider, model, prompt_tokens, completion_tokens)` | `POST /costs/estimate` |
190
+ | `list_model_costs(provider)` | `GET /costs/models` |
191
+ | `get_guardrails_summary(window_hours)` | `GET /guardrails/summary` |
192
+
193
+ ## Requirements
194
+
195
+ - Python 3.9+
196
+ - `httpx >= 0.26.0`
197
+
198
+ ## License
199
+
200
+ MIT
@@ -0,0 +1,169 @@
1
+ # llm-tracking
2
+
3
+ Python SDK for [LogicGaze](https://github.com/yourusername/tracker) — an AI-native observability platform.
4
+ All LLM calls are routed through the LogicGaze gateway, which records traces, spans, token usage, and cost automatically.
5
+
6
+ ## Installation
7
+
8
+ ```bash
9
+ pip install llm-tracking
10
+ ```
11
+
12
+ ## Quick Start
13
+
14
+ ### 1. Initialize once at startup
15
+
16
+ ```python
17
+ import llm_tracking
18
+
19
+ llm_tracking.init(
20
+ api_key="lgz_...", # LogicGaze API key (or set LLM_TRACKING_API_KEY)
21
+ base_url="http://localhost:8000", # your LogicGaze backend URL
22
+ )
23
+ ```
24
+
25
+ ### 2. Wrap your AI client
26
+
27
+ **OpenAI**
28
+ ```python
29
+ from openai import OpenAI
30
+ import llm_tracking
31
+
32
+ llm_tracking.init(api_key="lgz_...")
33
+ client = llm_tracking.wrap_openai(OpenAI())
34
+
35
+ response = client.chat.completions.create(
36
+ model="gpt-4o",
37
+ messages=[{"role": "user", "content": "Hello!"}],
38
+ )
39
+ print(response.choices[0].message.content)
40
+ ```
41
+
42
+ **Anthropic**
43
+ ```python
44
+ from anthropic import Anthropic
45
+ import llm_tracking
46
+
47
+ llm_tracking.init(api_key="lgz_...")
48
+ client = llm_tracking.wrap_anthropic(Anthropic())
49
+
50
+ response = client.messages.create(
51
+ model="claude-3-5-sonnet-20241022",
52
+ max_tokens=1024,
53
+ messages=[{"role": "user", "content": "Hello!"}],
54
+ )
55
+ print(response.content[0].text)
56
+ ```
57
+
58
+ > **Note:** The wrapped client routes calls through the LogicGaze gateway.
59
+ > The AI provider credentials must be configured in your LogicGaze backend, not in the client app.
60
+
61
+ ### 3. Group calls with `TraceContext`
62
+
63
+ ```python
64
+ from llm_tracking import TraceContext, wrap_openai
65
+ from openai import OpenAI
66
+
67
+ client = wrap_openai(OpenAI())
68
+
69
+ with TraceContext(session_id="sess-abc", user_id="user-42", service_name="chat-api"):
70
+ # Both calls share the same session in the trace viewer
71
+ client.chat.completions.create(model="gpt-4o", messages=[...])
72
+ client.chat.completions.create(model="gpt-4o", messages=[...])
73
+ ```
74
+
75
+ ### 4. Use `@traceable` on functions
76
+
77
+ ```python
78
+ from llm_tracking import traceable, wrap_openai
79
+ from openai import OpenAI
80
+
81
+ client = wrap_openai(OpenAI())
82
+
83
+ @traceable(session_id="sess-1", service_name="recommendation-engine")
84
+ def recommend(user_query: str):
85
+ return client.chat.completions.create(
86
+ model="gpt-4o",
87
+ messages=[{"role": "user", "content": user_query}],
88
+ )
89
+
90
+ # Async functions are supported too
91
+ @traceable(service_name="summarizer")
92
+ async def summarize(text: str):
93
+ return await client.chat.completions.create(
94
+ model="gpt-4o",
95
+ messages=[{"role": "user", "content": f"Summarize: {text}"}],
96
+ )
97
+ ```
98
+
99
+ ### 5. Query traces programmatically
100
+
101
+ ```python
102
+ from llm_tracking import get_client
103
+
104
+ lg = get_client()
105
+
106
+ # List recent traces
107
+ traces = lg.list_traces(service_name="chat-api", page_size=20)
108
+
109
+ # Get a specific trace with all spans
110
+ trace = lg.get_trace("trace-uuid-here", include_spans=True)
111
+
112
+ # Dashboard overview (last 24 h)
113
+ overview = lg.get_dashboard(window_hours=24)
114
+ print(overview["total_requests"], overview["total_cost_usd"])
115
+
116
+ # Estimate cost before a call
117
+ estimate = lg.estimate_cost("openai", "gpt-4o", prompt_tokens=500, completion_tokens=200)
118
+ ```
119
+
120
+ ## Configuration
121
+
122
+ | Parameter | Environment variable | Default |
123
+ |-----------|---------------------|---------|
124
+ | `api_key` | `LLM_TRACKING_API_KEY` | — |
125
+ | `base_url` | — | `http://localhost:8000` |
126
+ | `timeout` | — | `30.0` s |
127
+
128
+ ## API Reference
129
+
130
+ ### `llm_tracking.init(api_key, base_url, timeout)`
131
+ Initialize the global client. Call once at startup.
132
+
133
+ ### `wrap_openai(client, *, service_name=None)`
134
+ Patches `client.chat.completions.create` (sync & async). Returns the same client object.
135
+
136
+ ### `wrap_anthropic(client, *, service_name=None)`
137
+ Patches `client.messages.create` (sync & async). Returns the same client object.
138
+
139
+ ### `TraceContext(*, project, trace_id, session_id, user_id, service_name, tags)`
140
+ Context manager (sync & async). Sets metadata injected into every gateway call made within the block.
141
+
142
+ ### `@traceable(*, name, project, session_id, user_id, service_name, tags, run_type)`
143
+ Decorator. Wraps the function body in a `TraceContext`. Works with both sync and async functions. Can be used with or without arguments.
144
+
145
+ ### `LogicGazeClient` methods
146
+
147
+ | Method | Backend endpoint |
148
+ |--------|-----------------|
149
+ | `chat_completion(provider, model, messages, **kwargs)` | `POST /gateway/chat/completions` |
150
+ | `achat_completion(...)` | async version of above |
151
+ | `list_traces(**filters)` | `GET /traces` |
152
+ | `get_trace(trace_id, include_spans)` | `GET /traces/{id}` |
153
+ | `get_spans(trace_id)` | `GET /traces/{id}/spans` |
154
+ | `get_agent_graph(trace_id)` | `GET /traces/{id}/agent-graph` |
155
+ | `get_dashboard(window_hours)` | `GET /dashboard/overview` |
156
+ | `get_model_distribution(window_hours)` | `GET /dashboard/model-distribution` |
157
+ | `get_provider_breakdown(window_hours)` | `GET /dashboard/provider-breakdown` |
158
+ | `estimate_cost(provider, model, prompt_tokens, completion_tokens)` | `POST /costs/estimate` |
159
+ | `list_model_costs(provider)` | `GET /costs/models` |
160
+ | `get_guardrails_summary(window_hours)` | `GET /guardrails/summary` |
161
+
162
+ ## Requirements
163
+
164
+ - Python 3.9+
165
+ - `httpx >= 0.26.0`
166
+
167
+ ## License
168
+
169
+ MIT
@@ -0,0 +1,42 @@
1
+ from llm_tracking.client import (
2
+ LogicGazeClient,
3
+ get_client,
4
+ set_client,
5
+ init,
6
+ )
7
+ from llm_tracking.context import (
8
+ TraceContext,
9
+ get_current_trace_id,
10
+ get_current_session_id,
11
+ get_current_user_id,
12
+ get_current_service_name,
13
+ get_current_tags,
14
+ get_current_project,
15
+ get_current_run_id, # backward-compat no-op
16
+ )
17
+ from llm_tracking.decorators import traceable
18
+ from llm_tracking.wrappers import wrap_openai, wrap_anthropic
19
+
20
+ __version__ = "1.1.0"
21
+
22
+ __all__ = [
23
+ # Client
24
+ "LogicGazeClient",
25
+ "get_client",
26
+ "set_client",
27
+ "init",
28
+ # Context
29
+ "TraceContext",
30
+ "get_current_trace_id",
31
+ "get_current_session_id",
32
+ "get_current_user_id",
33
+ "get_current_service_name",
34
+ "get_current_tags",
35
+ "get_current_project",
36
+ "get_current_run_id",
37
+ # Decorators
38
+ "traceable",
39
+ # Wrappers
40
+ "wrap_openai",
41
+ "wrap_anthropic",
42
+ ]
@@ -0,0 +1,299 @@
1
+ import os
2
+ import httpx
3
+ from typing import Any, Dict, List, Optional
4
+
5
+
6
+ class LogicGazeClient:
7
+ """HTTP client for the LogicGaze observability backend."""
8
+
9
+ def __init__(
10
+ self,
11
+ api_key: Optional[str] = None,
12
+ base_url: str = "http://localhost:8000",
13
+ timeout: float = 30.0,
14
+ ):
15
+ self.api_key = api_key or os.environ.get("LLM_TRACKING_API_KEY")
16
+ # Normalize: strip trailing slash, append /api/v1 once
17
+ base = base_url.rstrip("/")
18
+ if not base.endswith("/api/v1"):
19
+ base = f"{base}/api/v1"
20
+ self.base_url = base
21
+ self.timeout = timeout
22
+
23
+ if not self.api_key:
24
+ raise ValueError(
25
+ "api_key must be provided or set via LLM_TRACKING_API_KEY env var"
26
+ )
27
+
28
+ # ------------------------------------------------------------------
29
+ # Internal helpers
30
+ # ------------------------------------------------------------------
31
+
32
+ def _headers(self) -> Dict[str, str]:
33
+ return {
34
+ "Authorization": f"Bearer {self.api_key}",
35
+ "Content-Type": "application/json",
36
+ }
37
+
38
+ def _request(self, method: str, path: str, **kwargs) -> Any:
39
+ url = f"{self.base_url}{path}"
40
+ with httpx.Client(timeout=self.timeout) as client:
41
+ response = client.request(method, url, headers=self._headers(), **kwargs)
42
+ response.raise_for_status()
43
+ return response.json()
44
+
45
+ async def _arequest(self, method: str, path: str, **kwargs) -> Any:
46
+ url = f"{self.base_url}{path}"
47
+ async with httpx.AsyncClient(timeout=self.timeout) as client:
48
+ response = await client.request(
49
+ method, url, headers=self._headers(), **kwargs
50
+ )
51
+ response.raise_for_status()
52
+ return response.json()
53
+
54
+ # ------------------------------------------------------------------
55
+ # Gateway – LLM proxy (creates traces + spans automatically)
56
+ # ------------------------------------------------------------------
57
+
58
+ def chat_completion(
59
+ self,
60
+ provider: str,
61
+ model: str,
62
+ messages: List[Dict],
63
+ *,
64
+ temperature: Optional[float] = None,
65
+ max_tokens: Optional[int] = None,
66
+ stream: bool = False,
67
+ tools: Optional[List] = None,
68
+ system: Optional[str] = None,
69
+ session_id: Optional[str] = None,
70
+ user_id: Optional[str] = None,
71
+ service_name: Optional[str] = None,
72
+ trace_id: Optional[str] = None,
73
+ tags: Optional[Dict] = None,
74
+ **kwargs,
75
+ ) -> Dict:
76
+ """Send a chat completion request through the LogicGaze gateway.
77
+
78
+ The gateway calls the actual AI provider and automatically records a
79
+ Trace + Span with token counts, cost, and latency.
80
+ """
81
+ payload: Dict[str, Any] = {
82
+ "provider": provider,
83
+ "model": model,
84
+ "messages": messages,
85
+ "stream": stream,
86
+ }
87
+ if temperature is not None:
88
+ payload["temperature"] = temperature
89
+ if max_tokens is not None:
90
+ payload["max_tokens"] = max_tokens
91
+ if tools:
92
+ payload["tools"] = tools
93
+ if system:
94
+ payload["system"] = system
95
+ if session_id:
96
+ payload["session_id"] = session_id
97
+ if user_id:
98
+ payload["user_id"] = user_id
99
+ if service_name:
100
+ payload["service_name"] = service_name
101
+ if trace_id:
102
+ payload["trace_id"] = trace_id
103
+ if tags:
104
+ payload["tags"] = tags
105
+
106
+ return self._request("POST", "/gateway/chat/completions", json=payload)
107
+
108
+ async def achat_completion(
109
+ self,
110
+ provider: str,
111
+ model: str,
112
+ messages: List[Dict],
113
+ *,
114
+ temperature: Optional[float] = None,
115
+ max_tokens: Optional[int] = None,
116
+ stream: bool = False,
117
+ tools: Optional[List] = None,
118
+ system: Optional[str] = None,
119
+ session_id: Optional[str] = None,
120
+ user_id: Optional[str] = None,
121
+ service_name: Optional[str] = None,
122
+ trace_id: Optional[str] = None,
123
+ tags: Optional[Dict] = None,
124
+ **kwargs,
125
+ ) -> Dict:
126
+ """Async version of chat_completion."""
127
+ payload: Dict[str, Any] = {
128
+ "provider": provider,
129
+ "model": model,
130
+ "messages": messages,
131
+ "stream": stream,
132
+ }
133
+ if temperature is not None:
134
+ payload["temperature"] = temperature
135
+ if max_tokens is not None:
136
+ payload["max_tokens"] = max_tokens
137
+ if tools:
138
+ payload["tools"] = tools
139
+ if system:
140
+ payload["system"] = system
141
+ if session_id:
142
+ payload["session_id"] = session_id
143
+ if user_id:
144
+ payload["user_id"] = user_id
145
+ if service_name:
146
+ payload["service_name"] = service_name
147
+ if trace_id:
148
+ payload["trace_id"] = trace_id
149
+ if tags:
150
+ payload["tags"] = tags
151
+
152
+ return await self._arequest(
153
+ "POST", "/gateway/chat/completions", json=payload
154
+ )
155
+
156
+ # ------------------------------------------------------------------
157
+ # Traces (read-only – traces are created by the gateway)
158
+ # ------------------------------------------------------------------
159
+
160
+ def list_traces(
161
+ self,
162
+ *,
163
+ page: int = 1,
164
+ page_size: int = 50,
165
+ status: Optional[str] = None,
166
+ service_name: Optional[str] = None,
167
+ session_id: Optional[str] = None,
168
+ model: Optional[str] = None,
169
+ start_time: Optional[str] = None,
170
+ end_time: Optional[str] = None,
171
+ ) -> Dict:
172
+ """List traces with optional filters. Returns TracesListResponse."""
173
+ params: Dict[str, Any] = {"page": page, "page_size": page_size}
174
+ if status:
175
+ params["status"] = status
176
+ if service_name:
177
+ params["service_name"] = service_name
178
+ if session_id:
179
+ params["session_id"] = session_id
180
+ if model:
181
+ params["model"] = model
182
+ if start_time:
183
+ params["start_time"] = start_time
184
+ if end_time:
185
+ params["end_time"] = end_time
186
+ return self._request("GET", "/traces", params=params)
187
+
188
+ def get_trace(self, trace_id: str, *, include_spans: bool = False) -> Dict:
189
+ """Get a single trace by ID. Pass include_spans=True to embed spans."""
190
+ params = {"include_spans": include_spans}
191
+ return self._request("GET", f"/traces/{trace_id}", params=params)
192
+
193
+ def get_spans(self, trace_id: str) -> List[Dict]:
194
+ """Get all spans for a trace."""
195
+ return self._request("GET", f"/traces/{trace_id}/spans")
196
+
197
+ def get_agent_graph(self, trace_id: str) -> Dict:
198
+ """Get the agent execution graph for a trace."""
199
+ return self._request("GET", f"/traces/{trace_id}/agent-graph")
200
+
201
+ # ------------------------------------------------------------------
202
+ # Dashboard analytics
203
+ # ------------------------------------------------------------------
204
+
205
+ def get_dashboard(self, *, window_hours: int = 24) -> Dict:
206
+ """Get overview metrics (requests, cost, latency, errors)."""
207
+ return self._request(
208
+ "GET", "/dashboard/overview", params={"window_hours": window_hours}
209
+ )
210
+
211
+ def get_model_distribution(self, *, window_hours: int = 24) -> List[Dict]:
212
+ return self._request(
213
+ "GET",
214
+ "/dashboard/model-distribution",
215
+ params={"window_hours": window_hours},
216
+ )
217
+
218
+ def get_provider_breakdown(self, *, window_hours: int = 24) -> List[Dict]:
219
+ return self._request(
220
+ "GET",
221
+ "/dashboard/provider-breakdown",
222
+ params={"window_hours": window_hours},
223
+ )
224
+
225
+ # ------------------------------------------------------------------
226
+ # Cost utilities
227
+ # ------------------------------------------------------------------
228
+
229
+ def estimate_cost(
230
+ self,
231
+ provider: str,
232
+ model: str,
233
+ prompt_tokens: int,
234
+ completion_tokens: int,
235
+ ) -> Dict:
236
+ """Estimate cost for a given model + token counts."""
237
+ return self._request(
238
+ "POST",
239
+ "/costs/estimate",
240
+ json={
241
+ "provider": provider,
242
+ "model": model,
243
+ "prompt_tokens": prompt_tokens,
244
+ "completion_tokens": completion_tokens,
245
+ },
246
+ )
247
+
248
+ def list_model_costs(self, *, provider: Optional[str] = None) -> Dict:
249
+ """Return the pricing catalog. Optionally filter by provider."""
250
+ params = {}
251
+ if provider:
252
+ params["provider"] = provider
253
+ return self._request("GET", "/costs/models", params=params)
254
+
255
+ # ------------------------------------------------------------------
256
+ # Guardrails summary
257
+ # ------------------------------------------------------------------
258
+
259
+ def get_guardrails_summary(self, *, window_hours: int = 24) -> Dict:
260
+ return self._request(
261
+ "GET",
262
+ "/guardrails/summary",
263
+ params={"window_hours": window_hours},
264
+ )
265
+
266
+
267
+ # ---------------------------------------------------------------------------
268
+ # Global singleton
269
+ # ---------------------------------------------------------------------------
270
+ _client: Optional[LogicGazeClient] = None
271
+
272
+
273
+ def init(
274
+ api_key: Optional[str] = None,
275
+ base_url: str = "http://localhost:8000",
276
+ timeout: float = 30.0,
277
+ ) -> LogicGazeClient:
278
+ """Initialize the global SDK client.
279
+
280
+ Call once at application startup::
281
+
282
+ import llm_tracking
283
+ llm_tracking.init(api_key="lgz_...", base_url="https://your-backend")
284
+ """
285
+ global _client
286
+ _client = LogicGazeClient(api_key=api_key, base_url=base_url, timeout=timeout)
287
+ return _client
288
+
289
+
290
+ def get_client() -> LogicGazeClient:
291
+ global _client
292
+ if _client is None:
293
+ _client = LogicGazeClient()
294
+ return _client
295
+
296
+
297
+ def set_client(client: LogicGazeClient) -> None:
298
+ global _client
299
+ _client = client
@@ -0,0 +1,133 @@
1
+ import contextvars
2
+ from typing import Any, Dict, Optional
3
+
4
+
5
+ # ---------------------------------------------------------------------------
6
+ # Per-request context variables (thread-safe, async-safe via contextvars)
7
+ # ---------------------------------------------------------------------------
8
+
9
+ _current_trace_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
10
+ "current_trace_id", default=None
11
+ )
12
+ _current_session_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
13
+ "current_session_id", default=None
14
+ )
15
+ _current_user_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
16
+ "current_user_id", default=None
17
+ )
18
+ _current_service_name: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
19
+ "current_service_name", default=None
20
+ )
21
+ _current_tags: contextvars.ContextVar[Optional[Dict]] = contextvars.ContextVar(
22
+ "current_tags", default=None
23
+ )
24
+ _current_project: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
25
+ "current_project", default=None
26
+ )
27
+
28
+
29
+ # ---------------------------------------------------------------------------
30
+ # Context manager
31
+ # ---------------------------------------------------------------------------
32
+
33
+
34
+ class TraceContext:
35
+ """Context manager that injects tracing metadata into all LLM calls made
36
+ within the block (works with both sync and async ``with`` statements).
37
+
38
+ Example::
39
+
40
+ with TraceContext(session_id="sess-123", user_id="user-456"):
41
+ client.chat.completions.create(...) # tagged automatically
42
+ """
43
+
44
+ def __init__(
45
+ self,
46
+ *,
47
+ project: Optional[str] = None,
48
+ trace_id: Optional[str] = None,
49
+ session_id: Optional[str] = None,
50
+ user_id: Optional[str] = None,
51
+ service_name: Optional[str] = None,
52
+ tags: Optional[Dict] = None,
53
+ ):
54
+ self.project = project
55
+ self.trace_id = trace_id
56
+ self.session_id = session_id
57
+ self.user_id = user_id
58
+ self.service_name = service_name
59
+ self.tags = tags
60
+ self._tokens: list = []
61
+
62
+ def _enter(self):
63
+ if self.trace_id is not None:
64
+ self._tokens.append(_current_trace_id.set(self.trace_id))
65
+ if self.session_id is not None:
66
+ self._tokens.append(_current_session_id.set(self.session_id))
67
+ if self.user_id is not None:
68
+ self._tokens.append(_current_user_id.set(self.user_id))
69
+ if self.service_name is not None:
70
+ self._tokens.append(_current_service_name.set(self.service_name))
71
+ if self.tags is not None:
72
+ self._tokens.append(_current_tags.set(self.tags))
73
+ if self.project is not None:
74
+ self._tokens.append(_current_project.set(self.project))
75
+ return self
76
+
77
+ def _exit(self):
78
+ for token in reversed(self._tokens):
79
+ token.var.reset(token)
80
+ self._tokens.clear()
81
+
82
+ def __enter__(self):
83
+ return self._enter()
84
+
85
+ def __exit__(self, *_):
86
+ self._exit()
87
+ return False
88
+
89
+ async def __aenter__(self):
90
+ return self._enter()
91
+
92
+ async def __aexit__(self, *_):
93
+ self._exit()
94
+ return False
95
+
96
+
97
+ # ---------------------------------------------------------------------------
98
+ # Accessor helpers (used by wrappers / decorators)
99
+ # ---------------------------------------------------------------------------
100
+
101
+
102
+ def get_current_trace_id() -> Optional[str]:
103
+ return _current_trace_id.get()
104
+
105
+
106
+ def get_current_session_id() -> Optional[str]:
107
+ return _current_session_id.get()
108
+
109
+
110
+ def get_current_user_id() -> Optional[str]:
111
+ return _current_user_id.get()
112
+
113
+
114
+ def get_current_service_name() -> Optional[str]:
115
+ return _current_service_name.get()
116
+
117
+
118
+ def get_current_tags() -> Optional[Dict]:
119
+ return _current_tags.get()
120
+
121
+
122
+ def get_current_project() -> Optional[str]:
123
+ return _current_project.get()
124
+
125
+
126
+ def get_current_run_id() -> Optional[str]:
127
+ """Kept for backward compatibility — not used by gateway-based tracing."""
128
+ return None
129
+
130
+
131
+ def set_current_run_id(run_id: str) -> None:
132
+ """Kept for backward compatibility — no-op with gateway-based tracing."""
133
+ pass
@@ -0,0 +1,70 @@
1
+ """
2
+ @traceable decorator
3
+
4
+ Sets tracing context (session_id, user_id, service_name, tags) for the
5
+ duration of the decorated function so that any wrapped LLM client calls
6
+ made inside automatically include those fields in the gateway request.
7
+ """
8
+
9
+ import asyncio
10
+ import functools
11
+ import inspect
12
+ import os
13
+ from typing import Callable, Dict, Optional
14
+
15
+ from llm_tracking.context import TraceContext
16
+
17
+
18
+ def traceable(
19
+ func: Optional[Callable] = None,
20
+ *,
21
+ name: Optional[str] = None,
22
+ project: Optional[str] = None,
23
+ session_id: Optional[str] = None,
24
+ user_id: Optional[str] = None,
25
+ service_name: Optional[str] = None,
26
+ tags: Optional[Dict] = None,
27
+ run_type: str = "generic", # kept for backward compatibility
28
+ ):
29
+ """Mark a function so that all LLM calls inside it are traced together.
30
+
31
+ Sets :class:`~llm_tracking.context.TraceContext` for the function's
32
+ duration. Both sync and async functions are supported.
33
+
34
+ Can be used with or without arguments::
35
+
36
+ @traceable
37
+ def my_func(): ...
38
+
39
+ @traceable(session_id="sess-1", service_name="chat-api")
40
+ async def my_async_func(): ...
41
+ """
42
+
43
+ def decorator(fn: Callable) -> Callable:
44
+ ctx_kwargs = dict(
45
+ project=project or os.environ.get("LLM_TRACKING_PROJECT"),
46
+ session_id=session_id,
47
+ user_id=user_id,
48
+ service_name=service_name or fn.__module__,
49
+ tags=tags,
50
+ )
51
+ # Strip None values so TraceContext doesn't overwrite existing ctx vars
52
+ ctx_kwargs = {k: v for k, v in ctx_kwargs.items() if v is not None}
53
+
54
+ if inspect.iscoroutinefunction(fn):
55
+ @functools.wraps(fn)
56
+ async def async_wrapper(*args, **kwargs):
57
+ async with TraceContext(**ctx_kwargs):
58
+ return await fn(*args, **kwargs)
59
+ return async_wrapper
60
+ else:
61
+ @functools.wraps(fn)
62
+ def sync_wrapper(*args, **kwargs):
63
+ with TraceContext(**ctx_kwargs):
64
+ return fn(*args, **kwargs)
65
+ return sync_wrapper
66
+
67
+ # Support both @traceable and @traceable(...) usage
68
+ if func is not None:
69
+ return decorator(func)
70
+ return decorator
@@ -0,0 +1,263 @@
1
+ """
2
+ Wrappers for OpenAI and Anthropic SDK clients.
3
+
4
+ Instead of calling the provider directly, all calls are routed through the
5
+ LogicGaze gateway (POST /api/v1/gateway/chat/completions), which records a
6
+ Trace + Span automatically and then forwards the request to the real provider.
7
+ """
8
+
9
+ import asyncio
10
+ import inspect
11
+ from typing import Any, Dict, List, Optional
12
+
13
+ from llm_tracking.client import get_client
14
+ from llm_tracking.context import (
15
+ get_current_trace_id,
16
+ get_current_session_id,
17
+ get_current_user_id,
18
+ get_current_service_name,
19
+ get_current_tags,
20
+ )
21
+
22
+
23
+ # ---------------------------------------------------------------------------
24
+ # Lightweight response shims
25
+ # Mimic native SDK response objects so callers never have to change their code.
26
+ # ---------------------------------------------------------------------------
27
+
28
+
29
+ class _Usage:
30
+ __slots__ = ("prompt_tokens", "completion_tokens", "total_tokens",
31
+ "input_tokens", "output_tokens")
32
+
33
+ def __init__(self, data: Dict):
34
+ self.prompt_tokens = data.get("prompt_tokens", 0)
35
+ self.completion_tokens = data.get("completion_tokens", 0)
36
+ self.total_tokens = data.get("total_tokens", 0)
37
+ # Anthropic aliases
38
+ self.input_tokens = self.prompt_tokens
39
+ self.output_tokens = self.completion_tokens
40
+
41
+
42
+ class _Message:
43
+ __slots__ = ("role", "content", "tool_calls")
44
+
45
+ def __init__(self, data: Dict):
46
+ self.role = data.get("role", "assistant")
47
+ self.content = data.get("content", "")
48
+ self.tool_calls = data.get("tool_calls")
49
+
50
+
51
+ class _Choice:
52
+ __slots__ = ("index", "message", "finish_reason")
53
+
54
+ def __init__(self, data: Dict):
55
+ self.index = data.get("index", 0)
56
+ self.message = _Message(data.get("message", {}))
57
+ self.finish_reason = data.get("finish_reason")
58
+
59
+
60
+ class OpenAIChatCompletion:
61
+ """OpenAI-compatible response object built from the gateway JSON response."""
62
+
63
+ def __init__(self, data: Dict):
64
+ self.id = data.get("id", "")
65
+ self.object = data.get("object", "chat.completion")
66
+ self.created = data.get("created")
67
+ self.model = data.get("model", "")
68
+ self.choices: List[_Choice] = [_Choice(c) for c in data.get("choices", [])]
69
+ self.usage = _Usage(data.get("usage", {})) if data.get("usage") else None
70
+ self._raw = data
71
+
72
+ def __repr__(self) -> str: # pragma: no cover
73
+ return (
74
+ f"ChatCompletion(id={self.id!r}, model={self.model!r}, "
75
+ f"choices={len(self.choices)})"
76
+ )
77
+
78
+
79
+ class _AnthropicContentBlock:
80
+ __slots__ = ("type", "text")
81
+
82
+ def __init__(self, data: Dict):
83
+ self.type = data.get("type", "text")
84
+ self.text = data.get("text", "") if self.type == "text" else None
85
+
86
+
87
+ class AnthropicMessage:
88
+ """Anthropic-compatible response object built from the gateway JSON response.
89
+
90
+ The gateway returns an OpenAI-format payload; this class converts it back
91
+ to the shape that Anthropic callers expect.
92
+ """
93
+
94
+ def __init__(self, data: Dict):
95
+ self.id = data.get("id", "")
96
+ self.type = "message"
97
+ self.role = "assistant"
98
+ self.model = data.get("model", "")
99
+
100
+ choices = data.get("choices", [])
101
+ if choices:
102
+ content_text = choices[0].get("message", {}).get("content", "") or ""
103
+ self.content = [
104
+ _AnthropicContentBlock({"type": "text", "text": content_text})
105
+ ]
106
+ self.stop_reason = choices[0].get("finish_reason")
107
+ else:
108
+ self.content = []
109
+ self.stop_reason = None
110
+
111
+ usage_data = data.get("usage", {})
112
+ self.usage = _Usage(usage_data) if usage_data else None
113
+ self._raw = data
114
+
115
+ def __repr__(self) -> str: # pragma: no cover
116
+ return (
117
+ f"Message(id={self.id!r}, model={self.model!r}, "
118
+ f"stop_reason={self.stop_reason!r})"
119
+ )
120
+
121
+
122
+ # ---------------------------------------------------------------------------
123
+ # Helpers
124
+ # ---------------------------------------------------------------------------
125
+
126
+
127
+ def _tracing_kwargs() -> Dict:
128
+ """Collect any tracing context set by TraceContext / @traceable."""
129
+ ctx: Dict = {}
130
+ if get_current_trace_id():
131
+ ctx["trace_id"] = get_current_trace_id()
132
+ if get_current_session_id():
133
+ ctx["session_id"] = get_current_session_id()
134
+ if get_current_user_id():
135
+ ctx["user_id"] = get_current_user_id()
136
+ if get_current_service_name():
137
+ ctx["service_name"] = get_current_service_name()
138
+ if get_current_tags():
139
+ ctx["tags"] = get_current_tags()
140
+ return ctx
141
+
142
+
143
+ # ---------------------------------------------------------------------------
144
+ # wrap_openai
145
+ # ---------------------------------------------------------------------------
146
+
147
+
148
+ def wrap_openai(client: Any, *, service_name: Optional[str] = None) -> Any:
149
+ """Patch an OpenAI client so every ``chat.completions.create`` call is
150
+ routed through the LogicGaze gateway for automatic tracing.
151
+
152
+ The backend must have the OpenAI provider configured with a valid API key.
153
+
154
+ Usage::
155
+
156
+ from openai import OpenAI
157
+ import llm_tracking
158
+ llm_tracking.init(api_key="lgz_...")
159
+
160
+ openai_client = llm_tracking.wrap_openai(OpenAI())
161
+ response = openai_client.chat.completions.create(
162
+ model="gpt-4o", messages=[...]
163
+ )
164
+ print(response.choices[0].message.content)
165
+ """
166
+ original_create = client.chat.completions.create
167
+
168
+ def _build_payload(kwargs: Dict) -> Dict:
169
+ payload = {
170
+ "provider": "openai",
171
+ "model": kwargs.get("model", "gpt-4o"),
172
+ "messages": kwargs.get("messages", []),
173
+ }
174
+ for field in ("temperature", "max_tokens", "stream", "tools"):
175
+ if kwargs.get(field) is not None:
176
+ payload[field] = kwargs[field]
177
+ if service_name:
178
+ payload.setdefault("service_name", service_name)
179
+ payload.update(_tracing_kwargs())
180
+ return payload
181
+
182
+ def sync_create(*args, **kwargs):
183
+ tracking_client = get_client()
184
+ payload = _build_payload(kwargs)
185
+ data = tracking_client.chat_completion(**payload)
186
+ return OpenAIChatCompletion(data)
187
+
188
+ async def async_create(*args, **kwargs):
189
+ tracking_client = get_client()
190
+ payload = _build_payload(kwargs)
191
+ data = await tracking_client.achat_completion(**payload)
192
+ return OpenAIChatCompletion(data)
193
+
194
+ if inspect.iscoroutinefunction(original_create):
195
+ client.chat.completions.create = async_create
196
+ else:
197
+ client.chat.completions.create = sync_create
198
+
199
+ return client
200
+
201
+
202
+ # ---------------------------------------------------------------------------
203
+ # wrap_anthropic
204
+ # ---------------------------------------------------------------------------
205
+
206
+
207
+ def wrap_anthropic(client: Any, *, service_name: Optional[str] = None) -> Any:
208
+ """Patch an Anthropic client so every ``messages.create`` call is routed
209
+ through the LogicGaze gateway for automatic tracing.
210
+
211
+ The backend must have the Anthropic provider configured with a valid API key.
212
+
213
+ Usage::
214
+
215
+ from anthropic import Anthropic
216
+ import llm_tracking
217
+ llm_tracking.init(api_key="lgz_...")
218
+
219
+ anthropic_client = llm_tracking.wrap_anthropic(Anthropic())
220
+ response = anthropic_client.messages.create(
221
+ model="claude-3-5-sonnet-20241022",
222
+ max_tokens=1024,
223
+ messages=[{"role": "user", "content": "Hello"}],
224
+ )
225
+ print(response.content[0].text)
226
+ """
227
+ original_create = client.messages.create
228
+
229
+ def _build_payload(kwargs: Dict) -> Dict:
230
+ payload = {
231
+ "provider": "anthropic",
232
+ "model": kwargs.get("model", "claude-3-5-sonnet-20241022"),
233
+ "messages": kwargs.get("messages", []),
234
+ }
235
+ for field in ("temperature", "max_tokens", "stream", "tools"):
236
+ if kwargs.get(field) is not None:
237
+ payload[field] = kwargs[field]
238
+ # Anthropic uses a top-level "system" parameter
239
+ if kwargs.get("system"):
240
+ payload["system"] = kwargs["system"]
241
+ if service_name:
242
+ payload.setdefault("service_name", service_name)
243
+ payload.update(_tracing_kwargs())
244
+ return payload
245
+
246
+ def sync_create(*args, **kwargs):
247
+ tracking_client = get_client()
248
+ payload = _build_payload(kwargs)
249
+ data = tracking_client.chat_completion(**payload)
250
+ return AnthropicMessage(data)
251
+
252
+ async def async_create(*args, **kwargs):
253
+ tracking_client = get_client()
254
+ payload = _build_payload(kwargs)
255
+ data = await tracking_client.achat_completion(**payload)
256
+ return AnthropicMessage(data)
257
+
258
+ if inspect.iscoroutinefunction(original_create):
259
+ client.messages.create = async_create
260
+ else:
261
+ client.messages.create = sync_create
262
+
263
+ return client
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "logicgaze"
7
+ version = "1.1.0"
8
+ description = "AI-native observability SDK for tracing, evaluating, and optimizing production LLM applications"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = {text = "MIT"}
12
+ authors = [
13
+ {name = "Vikneesh VG", email = "vikneeshwaran.k@ventragate.com"}
14
+ ]
15
+ keywords = ["llm", "tracing", "observability", "ai", "openai", "anthropic", "langchain", "logicgaze", "evaluation"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Intended Audience :: Developers",
19
+ "License :: OSI Approved :: MIT License",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.9",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Topic :: Software Development :: Libraries :: Python Modules",
27
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
28
+ ]
29
+ dependencies = [
30
+ "httpx>=0.26.0",
31
+ ]
32
+
33
+ [project.optional-dependencies]
34
+ dev = [
35
+ "pytest>=7.0.0",
36
+ "pytest-asyncio>=0.21.0",
37
+ "build>=1.0.0",
38
+ "twine>=4.0.0",
39
+ ]
40
+
41
+ [project.urls]
42
+ Homepage = "https://github.com/VikneeshVG/logicgaze"
43
+ Repository = "https://github.com/VikneeshVG/logicgaze"
44
+ Issues = "https://github.com/VikneeshVG/logicgaze/issues"
45
+
46
+ [tool.hatch.build.targets.wheel]
47
+ packages = ["llm_tracking"]