coaiajs 0.3.3 → 0.4.1

package/README.md

@@ -50,7 +50,7 @@ Import from the root, or from a subpath to pull in only what you need. Every ent
 | `coaiajs/github` | `listIssues`, `getIssue`, `getIssueComments`, `resetClient` |
 | `coaiajs/environment` | `EnvironmentManager`, `createEnvironment`, `findEnvironment` |
 | `coaiajs/version` | `getPackageVersion` |
-| `coaiajs/langfuse` | `LangfuseClient`, `LangfuseApiError`, traces/observations/prompts/datasets/scores/comments/media operations and formatters (53 exports) |
+| `coaiajs/langfuse` | Langfuse JS SDK v5/OpenTelemetry tracing plus v4 observations, prompts, datasets, scores, comments, media, projects, and formatters (55 exports) |
 | `coaiajs/narrative` | `KnowledgeGraphManager`, chart operations, markdown export, tool definitions (29 exports) |
 | `coaiajs/pde` | `SessionManager`, `StcMapper`, `handlePdeTool`, `PDE_MCP_TOOLS` (10 exports) |
 | `coaiajs/planning` | `parsePlan`, `planToSTC`, `syncToChart`, `syncToPlan`, `handlePlanningTool` (10 exports) |
@@ -132,6 +132,16 @@ npx coaia <command>          # or: npm i -g coaiajs && coaia <command>
 
 `coaia fuse prompts get <name>` outputs Markdown by default (`--md` is available explicitly); use the global `--json` option for JSON.
 
+### Langfuse v4 compatibility
+
+`coaia fuse` uses the current scoped Langfuse JS SDK v5. Trace writes are exported as immutable OpenTelemetry spans to `POST /api/public/otel/v1/traces` with ingestion version 4. Trace, observation, and session reads use Observations API v2; score reads use Scores API v3. The removed v4 concepts are reflected in the CLI: sessions are reconstructed from observations, and legacy trace-output patching is no longer exposed. Langfuse Cloud sunsets the legacy APIs on **November 16, 2026**.
+
+Migration references: [Langfuse v4](https://langfuse.com/docs/v4) · [versions and compatibility](https://langfuse.com/docs/compatibility) · [deprecated API mapping](https://langfuse.com/faq/all/deprecated-api-migration) · [custom ingestion migration](https://langfuse.com/integrations/native/opentelemetry/migration-to-v4) · [current OpenAPI reference](https://cloud.langfuse.com/generated/api/openapi.yml).
+
+### Custom GPT observation actions
+
+[`agents/custom_gpt/ceremony-observations.yml`](./agents/custom_gpt/ceremony-observations.yml) is a focused OpenAPI 3.1 action specification for creating a root observation and appending child observations to the same Langfuse trace through OTLP/HTTP JSON. It contains 20 core actions—below the 30-action limit—and omits media and destructive operations. Setup, authentication, ID/timestamp rules, and ready-to-paste GPT instructions are in [`ceremony-observations.instructions.md`](./agents/custom_gpt/ceremony-observations.instructions.md). The broader imported API surface remains available in [`ceremony.yml`](./agents/custom_gpt/ceremony.yml).
+
 ---
 
 ## 3. MCP Server
@@ -140,11 +150,11 @@ npx coaia <command>          # or: npm i -g coaiajs && coaia <command>
 npx coaiajs-mcp
 ```
 
-Serves **63 tools, 3 prompts, and 1 listable resource** over stdio.
+Serves **62 tools, 3 prompts, and 1 listable resource** over stdio.
 
 | Group | Count | Examples |
 |---|---|---|
-| coaiapy + Langfuse | 20 | `coaia_tash`, `coaia_fetch`, `coaia_fuse_trace_create`, `coaia_fuse_traces_list` |
+| coaiapy + Langfuse | 19 | `coaia_tash`, `coaia_fetch`, `coaia_fuse_trace_create`, `coaia_fuse_traces_list` |
 | Narrative / knowledge graph | 27 | `create_entities`, `read_graph`, `create_structural_tension_chart`, `perform_mmot_evaluation` |
 | PDE | 10 | `import_pde_decomposition`, `create_stc_from_pde`, `complete_session` |
 | Planning | 6 | `parse_plan_structural`, `plan_to_stc`, `sync_plan_to_chart`, `pde_to_plan` |
@@ -162,7 +172,7 @@ Set `COAIAJS_FEATURES` to control the exposed tool set (default `STANDARD`):
 | Level | Effect |
 |---|---|
 | `MINIMAL` | Core tash/fetch and essential graph tools |
-| `STANDARD` | Default — the 63 tools above |
+| `STANDARD` | Default — the 62 tools above |
 | `OBSERVABILITY` | Same set as `STANDARD` |
 | `FULL` | Everything, including media tools |
 

package/agents/custom_gpt/ceremony-observations.instructions.md

@@ -0,0 +1,173 @@
+# Ceremony Observations GPT Action
+
+Use `ceremony-observations.yml` when the GPT must create Langfuse traces and append nested observations. It is intentionally smaller and more explicit than `ceremony.yml` so GPT Actions can reliably construct OTLP/HTTP JSON.
+
+## What this specification solves
+
+Langfuse v4 does not provide mutable REST trace and observation creation endpoints. A trace is the group of immutable observations sharing one `traceId`. The supported direct-ingestion path is:
+
+```text
+POST /api/public/otel/v1/traces
+Content-Type: application/json
+Authorization: Basic <base64(public-key:secret-key)>
+x-langfuse-ingestion-version: 4
+```
+
+The `observations_export` action exposes that endpoint with a constrained OTLP schema and examples. It supports both:
+
+1. Creating a trace by sending a root span without `parentSpanId`.
+2. Appending an observation by reusing the trace ID and setting `parentSpanId` to an existing observation/span ID.
+
+The file has **20 actions**, below the stated 30-action limit. Scores remain in this specification because the complete focused surface still fits. Media and destructive delete actions are omitted.
+
+## Configure the Custom GPT
+
+1. Import `ceremony-observations.yml` as the GPT Action schema.
+2. If the Langfuse project is not in the EU region, replace the server URL first:
+   - US: `https://us.cloud.langfuse.com`
+   - Japan: `https://jp.cloud.langfuse.com`
+   - HIPAA: `https://hipaa.cloud.langfuse.com`
+   - Self-hosted: the deployment's public base URL
+3. In the Action authentication UI choose **API Key** with a custom header:
+   - Header name: `Authorization`
+   - Value: `Basic BASE64_VALUE`
+   - `BASE64_VALUE` is the base64 encoding of `LANGFUSE_PUBLIC_KEY:LANGFUSE_SECRET_KEY` without a trailing newline.
+4. Never put either Langfuse key or the encoded Authorization value in GPT instructions, knowledge files, or conversation messages.
+5. Keep Code Interpreter/Data Analysis enabled if available. Before an export, use it to generate IDs and current timestamps rather than inventing them:
+
+   ```python
+   import secrets, time
+   trace_id = secrets.token_hex(16)  # only for a new trace
+   span_id = secrets.token_hex(8)    # fresh for every observation
+   start_ns = time.time_ns()
+   # perform/describe the observed work
+   end_ns = max(time.time_ns(), start_ns)
+   ```
+
+The ingestion operation also declares the required `x-langfuse-ingestion-version` action header with the only allowed value `4`. If a GPT Actions client omits this non-auth header, Langfuse documents that direct OTLP ingestion still works but may take up to ten minutes to appear in v4 reads. A proxy is required if the client cannot send the header and real-time visibility is mandatory.
+
+## Recommended GPT instructions
+
+Add the following behavior to the GPT's instructions:
+
+```markdown
+### Langfuse tracing
+
+Use observations_export to record ceremony work.
+
+When starting a new trace:
+1. Generate a cryptographically random, non-zero, lowercase 32-hex traceId.
+2. Generate a cryptographically random, non-zero, lowercase 16-hex root spanId.
+3. Calculate current Unix epoch nanoseconds as a decimal string.
+4. Export one complete root span without parentSpanId.
+5. Preserve the returned/local traceId and root spanId for later steps.
+
+When adding an observation:
+1. Reuse the exact 32-hex traceId.
+2. Generate a fresh non-zero 16-hex spanId. Never reuse a spanId.
+3. Set parentSpanId to the exact 16-hex ID of its parent observation.
+4. Export a complete observation with start and end epoch-nanosecond strings.
+5. Repeat trace-level attributes on the child.
+
+Every span must include langfuse.observation.type. Allowed values are span,
+generation, or event. JSON input/output must be serialized into stringValue.
+For generations, include langfuse.observation.model.name and, when known,
+langfuse.observation.usage_details as a JSON string.
+
+Treat exported spans as immutable. Do not retry with the same spanId to edit a
+span. To record a correction or later result, append a new child event/span.
+
+After exporting, call observations_list with the traceId and fields
+core,basic,time,io,metadata,model,usage,trace_context to verify the hierarchy.
+Use each returned observation id as the span/parent ID for later children.
+```
+
+## Minimal append example
+
+The parent trace and root observation must already exist. Replace every example value with live values; do not copy IDs or timestamps literally.
+
+```json
+{
+  "resourceSpans": [
+    {
+      "resource": {
+        "attributes": [
+          {
+            "key": "service.name",
+            "value": { "stringValue": "custom-gpt-ceremony" }
+          }
+        ]
+      },
+      "scopeSpans": [
+        {
+          "scope": {
+            "name": "custom-gpt-ceremony",
+            "version": "0.4.0"
+          },
+          "spans": [
+            {
+              "traceId": "REPLACE_WITH_32_HEX_TRACE_ID",
+              "spanId": "REPLACE_16_HEX",
+              "parentSpanId": "REPLACE_16_HEX",
+              "name": "ceremony-step",
+              "kind": 1,
+              "startTimeUnixNano": "REPLACE_WITH_EPOCH_NANOSECONDS",
+              "endTimeUnixNano": "REPLACE_WITH_EPOCH_NANOSECONDS",
+              "attributes": [
+                {
+                  "key": "langfuse.observation.type",
+                  "value": { "stringValue": "span" }
+                },
+                {
+                  "key": "langfuse.trace.name",
+                  "value": { "stringValue": "ceremony" }
+                },
+                {
+                  "key": "langfuse.observation.input",
+                  "value": { "stringValue": "{\"step\":\"input\"}" }
+                },
+                {
+                  "key": "langfuse.observation.output",
+                  "value": { "stringValue": "{\"status\":\"complete\"}" }
+                }
+              ],
+              "status": { "code": 1 }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Included action groups
+
+| Group | Actions |
+|---|---:|
+| Observations and trace ingestion | 2 |
+| Projects | 1 |
+| Prompts | 4 |
+| Datasets and dataset items | 6 |
+| Scores and score configurations | 5 |
+| Comments | 2 |
+| **Total** | **20** |
+
+## Why there are not separate create-trace and append-observation actions
+
+OpenAPI allows one operation for each HTTP method/path pair, and Langfuse uses the same OTLP endpoint for both behaviors. The `observations_export` action distinguishes them through span context:
+
+- root: new `traceId`, new `spanId`, no `parentSpanId`
+- child: existing `traceId`, new `spanId`, existing parent `spanId`
+
+A friendlier pair of actions with bodies such as `{traceId, parentId, input, output}` would require a trusted proxy that transforms those requests into OTLP and adds the ingestion-version header. An OpenAPI document alone cannot change Langfuse's wire contract.
+
+## Primary references
+
+- Langfuse OpenTelemetry integration: https://langfuse.com/integrations/native/opentelemetry
+- Langfuse observability data model: https://langfuse.com/docs/observability/data-model
+- Langfuse current OpenAPI document: https://cloud.langfuse.com/generated/api/openapi.yml
+- OTLP JSON encoding: https://opentelemetry.io/docs/specs/otlp/#json-protobuf-encoding
+- OpenAI GPT Actions introduction: https://developers.openai.com/api/docs/actions/introduction
+- OpenAI GPT Action authentication: https://developers.openai.com/api/docs/actions/authentication
+- OpenAI GPT Actions getting started: https://developers.openai.com/api/docs/actions/getting-started