dv-pipecat-flows 0.0.23.dev1__tar.gz → 0.0.23.dev3__tar.gz

dv_pipecat_flows-0.0.23.dev3/.agents/skills/loki-logs/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: loki-logs
+description: Fetch and analyze pipecat application logs from Loki by call ID or call SID. Use when debugging call issues, investigating errors, or analyzing bot behavior for a specific call. Accepts a call_id (UUID) or call_sid (numeric string like 3341710001) and optional environment (staging/production).
+argument-hint: <call_id|call_sid> [staging|production]
+allowed-tools: Bash(curl *), Bash(jq *)
+---
+
+# Loki Logs Fetcher
+
+Fetch logs from Loki for a specific pipecat call and analyze them.
+
+## Parameters
+
+- `$0` — **call_id or call_sid** (required): Either a UUID (e.g. `f3df923e-d535-4eff-a3c8-fefbae0e73bf`) or a numeric call SID string (e.g. `3341710001`)
+- `$1` — **environment** (optional): `production` (default) or `staging`
+
+## Instructions
+
+When invoked, follow these steps:
+
+### 1. Parse arguments
+
+```
+IDENTIFIER = $0
+ENV = $1 (default: "production")
+```
+
+If `ENV` is `prod`, normalize it to `production`.
+If `IDENTIFIER` is missing, ask the user for it.
+
+Detect the identifier type:
+- **UUID format** (contains hyphens, hex chars, e.g. `f3df923e-d535-...`): This is a `call_id`
+- **Numeric string** (digits only, e.g. `3341710001`): This is a `call_sid`
+
+Both work the same way in the Loki query — they are used as a substring match (`|=`) against the log lines.
+
+### 2. Fetch logs from Loki
+
+Use the Loki HTTP API at `http://35.154.72.110:3100` to query logs.
+
+The LogQL query to use:
+
+```
+{application="pipecat", environment="<ENV>"} |= `<IDENTIFIER>` | json | level=~"(?i)DEBUG|INFO|WARNING|ERROR|FATAL" | line_format `{{.message}}`
+```
+
+Execute this curl command (default time range: last 24 hours):
+
+**Timezone note:** If the user provides a specific time or time range, treat it as **IST (Asia/Kolkata, UTC+5:30)**. Convert to UTC epoch before querying Loki.
+
+```bash
+# Calculate timestamps (nanoseconds) — default: last 24 hours
+END=$(date +%s)000000000
+START=$(( $(date +%s) - 86400 ))000000000
+
+curl -s "http://35.154.72.110:3100/loki/api/v1/query_range" \
+  --data-urlencode "query={application=\"pipecat\", environment=\"<ENV>\"} |= \`<IDENTIFIER>\` | json | level=~\"(?i)DEBUG|INFO|WARNING|ERROR|FATAL\" | line_format \`{{.message}}\`" \
+  --data-urlencode "start=$START" \
+  --data-urlencode "end=$END" \
+  --data-urlencode "limit=5000" \
+  --data-urlencode "direction=forward" | jq .
+```
+
+If the result set is empty and the environment was `production`, suggest trying `staging` (and vice versa).
+
+If the result set is empty for both, try expanding the time range to 48 hours.
+
+### 3. Parse and display the logs
+
+Extract the log lines from the Loki JSON response. The response structure is:
+
+```json
+{
+  "data": {
+    "result": [
+      {
+        "values": [
+          ["<timestamp_ns>", "<log_line>"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+Display the logs in chronological order (earliest first). Show:
+- Timestamp (human-readable)
+- Log level (if parseable)
+- Message content
+
+### 4. Analyze the logs
+
+After displaying the logs, provide a brief analysis:
+
+1. **Call timeline**: What happened during this call? (connected, greeted, conversation flow, ended)
+2. **Errors/warnings**: Highlight any ERROR or WARNING level logs
+3. **Tool calls**: List any function/tool calls made during the call
+4. **TTS/STT activity**: Note any speech-related events
+5. **Call outcome**: How did the call end? (normal hangup, error, transfer, timeout)
+6. **Anomalies**: Flag anything unusual (long silences, repeated errors, unexpected state transitions)
+
+### 5. Grafana link
+
+Always provide a clickable Grafana Explore link for the user to view the logs in the browser:
+
+```
+http://35.154.72.110:3000/explore?schemaVersion=1&panes=%7B%221f1%22%3A%7B%22datasource%22%3A%22eeey6hiactdz4c%22%2C%22queries%22%3A%5B%7B%22datasource%22%3A%7B%22type%22%3A%22loki%22%2C%22uid%22%3A%22eeey6hiactdz4c%22%7D%2C%22direction%22%3A%22backward%22%2C%22editorMode%22%3A%22code%22%2C%22expr%22%3A%22%7Bapplication%3D%5C%22pipecat%5C%22%2C+environment%3D%5C%22<ENV>%5C%22%7D+%7C%3D+%60<IDENTIFIER>%60+%7C+json+%7C+level%3D%7E%5C%22%28%3Fi%29DEBUG%7CINFO%7CWARNING%7CERROR%7C+FATAL%5C%22+%7C+line_format+%60%7B%7B.message%7D%7D%60%22%2C%22queryType%22%3A%22range%22%2C%22refId%22%3A%22A%22%7D%5D%2C%22range%22%3A%7B%22from%22%3A%22now-6h%22%2C%22to%22%3A%22now%22%7D%2C%22compact%22%3Afalse%7D%7D&orgId=1
+```
+
+Replace `<ENV>` and `<IDENTIFIER>` in the URL with the actual values (URL-encoded where needed).
+
+## Troubleshooting
+
+- If curl times out, the Loki instance may be under heavy load — retry with a shorter time range or lower limit.
+- If you get no results, confirm the call_id is correct and try the other environment.
+- For very old calls (>48h), increase the time range or ask the user for an approximate time window.
+- All user-provided times are in **IST (UTC+5:30)** — convert to UTC epoch before querying.
+
+## Reference
+
+For LogQL query syntax and more filtering options, see [query-reference.md](query-reference.md).

dv_pipecat_flows-0.0.23.dev3/.agents/skills/loki-logs/query-reference.md

@@ -0,0 +1,113 @@
+# LogQL Query Reference for Pipecat Logs
+
+## Base Query Pattern
+
+```logql
+{application="pipecat", environment="<env>"} |= `<call_id>` | json | level=~"(?i)DEBUG|INFO|WARNING|ERROR|FATAL" | line_format `{{.message}}`
+```
+
+## Common Variations
+
+### Filter by log level
+
+**Errors only:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | level=~"(?i)ERROR|FATAL" | line_format `{{.message}}`
+```
+
+**Warnings and above:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | level=~"(?i)WARNING|ERROR|FATAL" | line_format `{{.message}}`
+```
+
+### Filter by keyword
+
+**LLM-related logs:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | level=~"(?i)DEBUG|INFO|WARNING|ERROR|FATAL" | line_format `{{.message}}` |= "LLM"
+```
+
+**TTS-related logs:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | line_format `{{.message}}` |= "TTS"
+```
+
+**Tool/function call logs:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | line_format `{{.message}}` |~ "function|tool_call|generic_function"
+```
+
+**VAD/speech detection:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | line_format `{{.message}}` |~ "VAD|speaking|speech|silence|idle"
+```
+
+### Search across all calls in an environment
+
+**Recent errors (no call_id filter):**
+```logql
+{application="pipecat", environment="staging"} | json | level=~"(?i)ERROR|FATAL" | line_format `{{.message}}`
+```
+
+**By pod name:**
+```logql
+{application="pipecat", environment="staging", pod=~"pipecat-.*"} | json | line_format `{{.message}}`
+```
+
+## Loki API Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /loki/api/v1/query_range` | Query logs over a time range |
+| `GET /loki/api/v1/query` | Query logs at a single point in time |
+| `GET /loki/api/v1/labels` | List all label names |
+| `GET /loki/api/v1/label/<name>/values` | List values for a label |
+| `GET /loki/api/v1/tail` | Stream logs via WebSocket |
+
+### API Parameters for query_range
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `query` | LogQL query string | `{application="pipecat"}` |
+| `start` | Start timestamp (nanoseconds or RFC3339) | `1609459200000000000` |
+| `end` | End timestamp (nanoseconds or RFC3339) | `1609545600000000000` |
+| `limit` | Max entries to return | `5000` |
+| `direction` | Sort order: `forward` or `backward` | `forward` |
+| `step` | Query resolution step (for metrics) | `60s` |
+
+## Response Structure
+
+```json
+{
+  "status": "success",
+  "data": {
+    "resultType": "streams",
+    "result": [
+      {
+        "stream": {
+          "application": "pipecat",
+          "environment": "staging",
+          "level": "INFO"
+        },
+        "values": [
+          ["1700000000000000000", "log message here"],
+          ["1700000001000000000", "another log message"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Environment Values
+
+| Environment | Label Value | Description |
+|-------------|-------------|-------------|
+| Staging | `staging` | Test/staging environment |
+| Production | `production` | Live production environment |
+
+## Infrastructure
+
+- **Loki endpoint**: `http://35.154.72.110:3100`
+- **Grafana UI**: `http://35.154.72.110:3000`
+- **Loki datasource UID**: `eeey6hiactdz4c`

dv_pipecat_flows-0.0.23.dev3/.claude/skills/loki-logs/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: loki-logs
+description: Fetch and analyze pipecat application logs from Loki by call ID or call SID. Use when debugging call issues, investigating errors, or analyzing bot behavior for a specific call. Accepts a call_id (UUID) or call_sid (numeric string like 3341710001) and optional environment (staging/production).
+argument-hint: <call_id|call_sid> [staging|production]
+allowed-tools: Bash(curl *), Bash(jq *)
+---
+
+# Loki Logs Fetcher
+
+Fetch logs from Loki for a specific pipecat call and analyze them.
+
+## Parameters
+
+- `$0` — **call_id or call_sid** (required): Either a UUID (e.g. `f3df923e-d535-4eff-a3c8-fefbae0e73bf`) or a numeric call SID string (e.g. `3341710001`)
+- `$1` — **environment** (optional): `production` (default) or `staging`
+
+## Instructions
+
+When invoked, follow these steps:
+
+### 1. Parse arguments
+
+```
+IDENTIFIER = $0
+ENV = $1 (default: "production")
+```
+
+If `ENV` is `prod`, normalize it to `production`.
+If `IDENTIFIER` is missing, ask the user for it.
+
+Detect the identifier type:
+- **UUID format** (contains hyphens, hex chars, e.g. `f3df923e-d535-...`): This is a `call_id`
+- **Numeric string** (digits only, e.g. `3341710001`): This is a `call_sid`
+
+Both work the same way in the Loki query — they are used as a substring match (`|=`) against the log lines.
+
+### 2. Fetch logs from Loki
+
+Use the Loki HTTP API at `http://35.154.72.110:3100` to query logs.
+
+The LogQL query to use:
+
+```
+{application="pipecat", environment="<ENV>"} |= `<IDENTIFIER>` | json | level=~"(?i)DEBUG|INFO|WARNING|ERROR|FATAL" | line_format `{{.message}}`
+```
+
+Execute this curl command (default time range: last 24 hours):
+
+**Timezone note:** If the user provides a specific time or time range, treat it as **IST (Asia/Kolkata, UTC+5:30)**. Convert to UTC epoch before querying Loki.
+
+```bash
+# Calculate timestamps (nanoseconds) — default: last 24 hours
+END=$(date +%s)000000000
+START=$(( $(date +%s) - 86400 ))000000000
+
+curl -s "http://35.154.72.110:3100/loki/api/v1/query_range" \
+  --data-urlencode "query={application=\"pipecat\", environment=\"<ENV>\"} |= \`<IDENTIFIER>\` | json | level=~\"(?i)DEBUG|INFO|WARNING|ERROR|FATAL\" | line_format \`{{.message}}\`" \
+  --data-urlencode "start=$START" \
+  --data-urlencode "end=$END" \
+  --data-urlencode "limit=5000" \
+  --data-urlencode "direction=forward" | jq .
+```
+
+If the result set is empty and the environment was `production`, suggest trying `staging` (and vice versa).
+
+If the result set is empty for both, try expanding the time range to 48 hours.
+
+### 3. Parse and display the logs
+
+Extract the log lines from the Loki JSON response. The response structure is:
+
+```json
+{
+  "data": {
+    "result": [
+      {
+        "values": [
+          ["<timestamp_ns>", "<log_line>"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+Display the logs in chronological order (earliest first). Show:
+- Timestamp (human-readable)
+- Log level (if parseable)
+- Message content
+
+### 4. Analyze the logs
+
+After displaying the logs, provide a brief analysis:
+
+1. **Call timeline**: What happened during this call? (connected, greeted, conversation flow, ended)
+2. **Errors/warnings**: Highlight any ERROR or WARNING level logs
+3. **Tool calls**: List any function/tool calls made during the call
+4. **TTS/STT activity**: Note any speech-related events
+5. **Call outcome**: How did the call end? (normal hangup, error, transfer, timeout)
+6. **Anomalies**: Flag anything unusual (long silences, repeated errors, unexpected state transitions)
+
+### 5. Grafana link
+
+Always provide a clickable Grafana Explore link for the user to view the logs in the browser:
+
+```
+http://35.154.72.110:3000/explore?schemaVersion=1&panes=%7B%221f1%22%3A%7B%22datasource%22%3A%22eeey6hiactdz4c%22%2C%22queries%22%3A%5B%7B%22datasource%22%3A%7B%22type%22%3A%22loki%22%2C%22uid%22%3A%22eeey6hiactdz4c%22%7D%2C%22direction%22%3A%22backward%22%2C%22editorMode%22%3A%22code%22%2C%22expr%22%3A%22%7Bapplication%3D%5C%22pipecat%5C%22%2C+environment%3D%5C%22<ENV>%5C%22%7D+%7C%3D+%60<IDENTIFIER>%60+%7C+json+%7C+level%3D%7E%5C%22%28%3Fi%29DEBUG%7CINFO%7CWARNING%7CERROR%7C+FATAL%5C%22+%7C+line_format+%60%7B%7B.message%7D%7D%60%22%2C%22queryType%22%3A%22range%22%2C%22refId%22%3A%22A%22%7D%5D%2C%22range%22%3A%7B%22from%22%3A%22now-6h%22%2C%22to%22%3A%22now%22%7D%2C%22compact%22%3Afalse%7D%7D&orgId=1
+```
+
+Replace `<ENV>` and `<IDENTIFIER>` in the URL with the actual values (URL-encoded where needed).
+
+## Troubleshooting
+
+- If curl times out, the Loki instance may be under heavy load — retry with a shorter time range or lower limit.
+- If you get no results, confirm the call_id is correct and try the other environment.
+- For very old calls (>48h), increase the time range or ask the user for an approximate time window.
+- All user-provided times are in **IST (UTC+5:30)** — convert to UTC epoch before querying.
+
+## Reference
+
+For LogQL query syntax and more filtering options, see [query-reference.md](query-reference.md).

dv_pipecat_flows-0.0.23.dev3/.claude/skills/loki-logs/query-reference.md

@@ -0,0 +1,113 @@
+# LogQL Query Reference for Pipecat Logs
+
+## Base Query Pattern
+
+```logql
+{application="pipecat", environment="<env>"} |= `<call_id>` | json | level=~"(?i)DEBUG|INFO|WARNING|ERROR|FATAL" | line_format `{{.message}}`
+```
+
+## Common Variations
+
+### Filter by log level
+
+**Errors only:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | level=~"(?i)ERROR|FATAL" | line_format `{{.message}}`
+```
+
+**Warnings and above:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | level=~"(?i)WARNING|ERROR|FATAL" | line_format `{{.message}}`
+```
+
+### Filter by keyword
+
+**LLM-related logs:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | level=~"(?i)DEBUG|INFO|WARNING|ERROR|FATAL" | line_format `{{.message}}` |= "LLM"
+```
+
+**TTS-related logs:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | line_format `{{.message}}` |= "TTS"
+```
+
+**Tool/function call logs:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | line_format `{{.message}}` |~ "function|tool_call|generic_function"
+```
+
+**VAD/speech detection:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | line_format `{{.message}}` |~ "VAD|speaking|speech|silence|idle"
+```
+
+### Search across all calls in an environment
+
+**Recent errors (no call_id filter):**
+```logql
+{application="pipecat", environment="staging"} | json | level=~"(?i)ERROR|FATAL" | line_format `{{.message}}`
+```
+
+**By pod name:**
+```logql
+{application="pipecat", environment="staging", pod=~"pipecat-.*"} | json | line_format `{{.message}}`
+```
+
+## Loki API Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /loki/api/v1/query_range` | Query logs over a time range |
+| `GET /loki/api/v1/query` | Query logs at a single point in time |
+| `GET /loki/api/v1/labels` | List all label names |
+| `GET /loki/api/v1/label/<name>/values` | List values for a label |
+| `GET /loki/api/v1/tail` | Stream logs via WebSocket |
+
+### API Parameters for query_range
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `query` | LogQL query string | `{application="pipecat"}` |
+| `start` | Start timestamp (nanoseconds or RFC3339) | `1609459200000000000` |
+| `end` | End timestamp (nanoseconds or RFC3339) | `1609545600000000000` |
+| `limit` | Max entries to return | `5000` |
+| `direction` | Sort order: `forward` or `backward` | `forward` |
+| `step` | Query resolution step (for metrics) | `60s` |
+
+## Response Structure
+
+```json
+{
+  "status": "success",
+  "data": {
+    "resultType": "streams",
+    "result": [
+      {
+        "stream": {
+          "application": "pipecat",
+          "environment": "staging",
+          "level": "INFO"
+        },
+        "values": [
+          ["1700000000000000000", "log message here"],
+          ["1700000001000000000", "another log message"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Environment Values
+
+| Environment | Label Value | Description |
+|-------------|-------------|-------------|
+| Staging | `staging` | Test/staging environment |
+| Production | `production` | Live production environment |
+
+## Infrastructure
+
+- **Loki endpoint**: `http://35.154.72.110:3100`
+- **Grafana UI**: `http://35.154.72.110:3000`
+- **Loki datasource UID**: `eeey6hiactdz4c`

{dv_pipecat_flows-0.0.23.dev1 → dv_pipecat_flows-0.0.23.dev3}/.gitignore

@@ -71,6 +71,11 @@ npm-debug.log*
 *.njsproj
 *.sln
 *.sw?
+ringg-bot/eval/out/*
+ringg-bot/eval/inputs/*
+ringg-bot/eval/report/*
+ringg-bot/eval/samples/*
+ringg-bot/eval/comparison_analysis/*
 
 # Auto-generated docs
 docs/api