NarrativeTrace

https://narrativetrace.ai/docs
Admin
NarrativeTrace is an automated tracing and logging library that captures execution narratives,...
Tokens:15,396
Snippets:107
Trust Score:2.9
Update:1 day ago
Show doc for...
Tokens:
Raw
### Python: Before — three careful log lines

Source: https://narrativetrace.ai/

Manual logging example in Python using logger.info and logger.exception.

```Python
def place_order(self, req: OrderRequest) -> Order:
    logger.info("Placing order %s", req.id)
    try:
        customer = self._customers.find(req.id)
        price = self._catalog.price(req.sku)
        self._inventory.reserve(req.sku, req.qty)
        payment = self._payments.charge(price)
        order = self._orders.save(customer, payment)
        logger.info("Order succeeded %s", order.id)
        return order
    except Exception:
        logger.exception("Placing order failed %s", req.id)
        raise
```

--------------------------------

### Java: Before — three careful log lines

Source: https://narrativetrace.ai/

Manual logging example in Java using logger.info and logger.error with SLF4J-style placeholders.

```Java
public Order placeOrder(OrderRequest req) {
    logger.info("Placing order {}", req.id());
    try {
        var customer = customers.find(req.id());
        var price = catalog.price(req.sku());
        inventory.reserve(req.sku(), req.qty());
        var payment = payments.charge(price);
        var order = orders.save(customer, payment);
        logger.info("Order succeeded {}", order.id());
        return order;
    } catch (Exception e) {
        logger.error("Placing order failed {}", req.id(), e);
        throw e;
    }
}
```

--------------------------------

### C#: Before — three careful log lines

Source: https://narrativetrace.ai/

Manual logging example in C# using _logger.LogInformation and _logger.LogError.

```C#
public Order PlaceOrder(OrderRequest req)
{
    _logger.LogInformation("Placing order {OrderId}", req.Id);
    try
    {
        var customer = _customers.Find(req.Id);
        var price = _catalog.Price(req.Sku);
        _inventory.Reserve(req.Sku, req.Qty);
        var payment = _payments.Charge(price);
        var order = _orders.Save(customer, payment);
        _logger.LogInformation("Order succeeded {OrderId}", order.Id);
        return order;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Placing order failed {OrderId}", req.Id);
        throw;
    }
}
```

--------------------------------

### TypeScript: Before — three careful log lines

Source: https://narrativetrace.ai/

Manual logging example in TypeScript showing explicit logger.info and logger.error calls around order placement logic.

```TypeScript
placeOrder(req: OrderRequest): Order {
  logger.info({ orderId: req.id }, 'placing order');
  try {
    const customer = this.customers.find(req.id);
    const price = this.catalog.price(req.sku);
    this.inventory.reserve(req.sku, req.qty);
    const payment = this.payments.charge(price);
    const order = this.orders.save(customer, payment);
    logger.info({ orderId: order.id }, 'order succeeded');
    return order;
  } catch (err) {
    logger.error({ orderId: req.id, err }, 'placing order failed');
    throw err;
  }
}
```

--------------------------------

### NarrativeTrace suite completion output

Source: https://narrativetrace.ai/

Example output after running ./gradlew test, showing scenario count, clarity percentages, report location, and a summary of changes since the last green run.

```plaintext
NarrativeTrace — Suite complete
  5 scenarios recorded
  Clarity: 100% high | 0% moderate | 0% low
  Reports: build/narrativetrace
  Since last green: 4 scenarios unchanged · 1 changed:
    "Customer places order" (−1 call Customers.verifyGoodStanding)
```

--------------------------------

### Traditional app.log output for failed order

Source: https://narrativetrace.ai/

Example of a traditional application log showing an order failure with customer ID, product ID, and error type. This is the only clue an on-call engineer has.

```text
INFO  Placing order {customerId: "C-1234", productId: "SKU-KB", quantity: 2}
ERROR Order failed {customerId: "C-1234", productId: "SKU-KB", err: PaymentDeclinedError}
```

--------------------------------

### Approval failure diff output

Source: https://narrativetrace.ai/

Example output when approval mode is enabled (approval.set(true)) and a refactor changes the call structure. Shows the diff against the approved baseline and instructs to review the .received.nt file and run ./gradlew approveNarratives.

```plaintext
Narrative changed against the approved baseline
  src/test/narratives/OrderServiceTest/customer_places_order.approved.nt

  - OrderService.placeOrder(customerId, qty) → value
-   - Customers.verifyGoodStanding(customerId) → value
    - PricingService.calculate(qty) → value
    - PaymentService.charge(card) → value
    - OrderRepository.save(order) → value

  review the .received.nt, then: ./gradlew approveNarratives
```

--------------------------------

### Value-free trace for agents (customer_places_order.nt)

Source: https://narrativetrace.ai/

Shows a trace file (customer_places_order.nt) that contains no data or PII, making it safe for AI agents. It lists the sequence of calls and their return values without actual data.

```text
- OrderService.placeOrder(customerId, qty) → value
  - Customers.verifyGoodStanding(customerId) → value
  - PricingService.calculate(qty) → value
  - PaymentService.charge(card) → value
  - OrderRepository.save(order) → value
// no data, no PII, nothing to inject through
```

--------------------------------

### Python: Wrap a service with trace_object or @narrated decorator

Source: https://narrativetrace.ai/

Shows two ways to enable tracing: wrapping a service instance with trace_object, or using the @narrated decorator on a method. Requires Python 3.12+; @on_error stacks the same way for failure narration.

```Python
context = ContextVarNarrativeContext()
service = trace_object(OrderService(), context)

# or narrate a method by hand:
@narrated("Placing order of {quantity} {product_id} for customer {customer_id}")
def place_order(self, customer_id, product_id, quantity): ...
```

--------------------------------

### Python: After — code is the log

Source: https://narrativetrace.ai/

The same order placement logic without explicit logging, showing how NarrativeTrace captures the narrative automatically.

```Python
def place_order(self, req: OrderRequest) -> Order:
    customer = self._customers.find(req.id)
    price = self._catalog.price(req.sku)
    self._inventory.reserve(req.sku, req.qty)
    payment = self._payments.charge(price)
    return self._orders.save(customer, payment)
# Zero log lines.
# NarrativeTrace captures the narrative
# automatically.
```

--------------------------------

### Java: After — code is the log

Source: https://narrativetrace.ai/

The same order placement logic without explicit logging, showing how NarrativeTrace captures the narrative automatically.

```Java
public Order placeOrder(OrderRequest req) {
    var customer = customers.find(req.id());
    var price = catalog.price(req.sku());
    inventory.reserve(req.sku(), req.qty());
    var payment = payments.charge(price);
    return orders.save(customer, payment);
}
// Zero log lines.
// NarrativeTrace captures the narrative
// automatically.
```

--------------------------------

### Java: Wrap a service with NarrativeTraceProxy or @EnableNarrativeTrace

Source: https://narrativetrace.ai/

Shows two ways to enable tracing: wrapping a service instance with NarrativeTraceProxy.trace, or using the Spring @EnableNarrativeTrace annotation. Requires Java 17+ and Gradle 8+.

```Java
var context = new ThreadLocalNarrativeContext();
var service = NarrativeTraceProxy.trace(
    orderService, OrderService.class, context);

// or for Spring:
@EnableNarrativeTrace(
    basePackages = "com.example.app")
```

--------------------------------

### C#: After — code is the log

Source: https://narrativetrace.ai/

The same order placement logic without explicit logging, showing how NarrativeTrace captures the narrative automatically.

```C#
public Order PlaceOrder(OrderRequest req)
{
    var customer = _customers.Find(req.Id);
    var price = _catalog.Price(req.Sku);
    _inventory.Reserve(req.Sku, req.Qty);
    var payment = _payments.Charge(price);
    return _orders.Save(customer, payment);
}
// Zero log lines.
// NarrativeTrace captures the narrative
// automatically.
```

--------------------------------

### C#: Wrap a service with NarrativeTraceProxy or AddNarrativeTracing

Source: https://narrativetrace.ai/

Shows two ways to enable tracing: wrapping a service instance with NarrativeTraceProxy.Create, or using the DI container extension AddNarrativeTracing. Targets net10.0 and netstandard2.0, with NarrativeTrace.Legacy for .NET Framework 4.8.

```C#
var context = new SyncNarrativeContext(
    new NarrativeTraceConfig(TracingLevel.Detail));
var service = NarrativeTraceProxy
    .Create<IOrderService>(new OrderService(), context);

// or for the DI container:
services.AddNarrativeTracing(options => options
    .Namespaces("MyApp.Services", "MyApp.Domain"));
```

--------------------------------

### TypeScript: After — code is the log

Source: https://narrativetrace.ai/

The same order placement logic without explicit logging, showing how NarrativeTrace captures the narrative automatically.

```TypeScript
placeOrder(req: OrderRequest): Order {
  const customer = this.customers.find(req.id);
  const price = this.catalog.price(req.sku);
  this.inventory.reserve(req.sku, req.qty);
  const payment = this.payments.charge(price);
  return this.orders.save(customer, payment);
}
// Zero log lines.
// NarrativeTrace captures the narrative
// automatically.
```

--------------------------------

### TypeScript: Wrap a service with traceObject or @traced decorator

Source: https://narrativetrace.ai/

Shows two ways to enable tracing on a service: wrapping an instance with traceObject and specifying traced parameters, or using the @traced decorator on a method. Requires Node 20+ and TypeScript 5.0+ for the decorator form.

```TypeScript
const context = new AsyncNarrativeContext(
    new NarrativeTraceConfig());
const service = traceObject(orderService, context, {
  placeOrder: ["customerId", "productId", "quantity"],
});

// or on the class itself:
@traced("customerId", "productId", "quantity")
placeOrder(cId: string, pId: string, qty: number) {}
```

--------------------------------

### Python: Read the story with MarkdownRenderer

Source: https://narrativetrace.ai/

Calls the traced service method and prints the captured trace using MarkdownRenderer. Notes that in pytest, every test writes its own trace file.

```Python
service.place_order("C-1234", "SKU-KB", 2)

print(MarkdownRenderer().render(context.capture_trace()))

# pytest: every test writes
# its own trace file.
```

--------------------------------

### C#: Read the story with IndentedTextRenderer.Render

Source: https://narrativetrace.ai/

Calls the traced service method and prints the captured trace using IndentedTextRenderer.Render. Notes that in xUnit/NUnit, every test writes its own trace file.

```C#
service.PlaceOrder("C-1234", "SKU-KB", 2);

Console.WriteLine(
    IndentedTextRenderer.Render(
        context.CaptureTrace()));

// xUnit / NUnit: every test writes
// its own trace file.
```

--------------------------------

### Java: Read the story with IndentedTextRenderer

Source: https://narrativetrace.ai/

Calls the traced service method and prints the captured trace using IndentedTextRenderer. Notes that in JUnit 5/4, every test writes its own trace file.

```Java
service.placeOrder("C-1234", "SKU-KB", 2);

System.out.println(
  new IndentedTextRenderer()
      .render(context.captureTrace()));

// JUnit 5/4: every test writes
// its own trace file.
```

--------------------------------

### TASK.md specification for ClaimFlow

Source: https://narrativetrace.ai/

The full specification for the ClaimFlow claims intake service. It defines the domain, required behavior, deliverables, and reporting instructions for building a Java 17 application with Gradle.

```markdown
# Build task — Claims intake service (Java 17)

Build a small, self-contained Java 17 application called **ClaimFlow** that processes
insurance claims through a chain of collaborating services. It must build and test with
Gradle, and run as an executable demo.

This is a business-logic exercise, not an infrastructure one: everything is in-process
and in-memory. No database, no HTTP server, no external service, no network access.

## The domain

A claim is submitted and passes through five collaborating services. Each is its own
interface with its own implementation — do not collapse them into one class.

1. **PolicyService** — looks up a policy by `policyId`. A policy has a holder name, a
   coverage limit in whole cents, a deductible in whole cents, and an active flag.
2. **ClaimValidator** — rejects a claim that names an unknown policy, an inactive
   policy, a non-positive amount, or an incident date in the future.
3. **FraudScreen** — scores a claim from 0–100. Any claim scoring above 70 is referred
   rather than paid. Scoring may be simple and deterministic, but it must consider at
   least the claim amount relative to the coverage limit, and whether the same policy
   has had a prior claim in this run.
4. **ReserveLedger** — reserves funds against a policy's remaining coverage before
   payment, and can release a reservation. Reserving more than the remaining coverage
   fails.
5. **PayoutService** — pays an approved claim, given a payment token. Payment can fail;
   your demo must exercise at least one failing payment.

A **ClaimProcessor** orchestrates them and returns a `ClaimOutcome` describing what
happened: paid (with amount and transaction id), referred, or rejected (with a reason).

## Required behaviour

- Payout amount is `min(claimAmount, coverageLimit) - deductible`, never below zero.
- A claim must be validated, then screened, then reserved, then paid — in that order.
- **If payment fails after a reservation was made, the reservation must be released.**
- A referred claim is never paid and never reserves funds.
- Two claims against the same policy must respect the remaining coverage.
- The payment token is a credential and must never appear in any output your program
  produces.
- The claim holder's name is personal data; treat it accordingly in whatever your
  program writes out.

## Deliverables

1. A Gradle project that compiles under Java 17 and runs `./gradlew test` green.
2. Unit tests covering the behaviour above, including the failure paths.
3. A runnable demo (`./gradlew run` or a `main`) that exercises at least five scenarios:
   a straightforward paid claim, a claim above the coverage limit, a referred (high
   fraud score) claim, a rejected claim, and a claim whose payment fails after a
   reservation.
4. A short `FINDINGS.md` in the project root — see "What to report" below.

## What to report in FINDINGS.md

Write it for another engineer, not for us. Cover:

- What you built and how you verified it works.
- Anything that surprised you, went wrong, or took longer than expected.
- How you satisfied yourself that the compensation rule (release the reservation when
  payment fails) actually holds — what evidence do you have?
- How you satisfied yourself that the payment token never leaks into output.
- What you would want before running this in production.
- Anything about the tools or libraries you used that helped or got in your way.

Be honest and specific. A report that says everything went perfectly is less useful
than one that names what was awkward.
```

--------------------------------

### Human-readable prose render of a trace

Source: https://narrativetrace.ai/

Output of new ProseRenderer().render(trace) which converts a trace into a human-readable narrative. The prose reads as well as the names used in the code.

```text
The order service places an order for customer id "C-42", quantity 5:
  Customers verify good standing for "C-42", returning true.
  The pricing service calculates for quantity 5, returning 49.95.
  The payment service charges card [REDACTED], returning PaymentConfirmation(txId="T-9").
  The order repository saves the order, returning Order{id=ORD-1001, total=49.95}.
```

--------------------------------

### NarrativeTrace trace output for failed order

Source: https://narrativetrace.ai/

Shows the trace captured by NarrativeTrace for the same failed order, including detailed timing and the exact failing call (PaymentService.charge). This trace is automatically generated and includes data not present in the log, such as price and redacted card token.

```text
OrderService.placeOrder(customerId: "C-1234", productId: "SKU-KB", quantity: 2)
  CustomerService.findCustomer(customerId: "C-1234") → Customer{tier: "gold"} — 4ms
  ProductCatalogService.lookupPrice(productId: "SKU-KB") → 24.99 — 2ms
  InventoryService.reserve(productId: "SKU-KB", quantity: 2) → Reservation{productId: "SKU-KB", quantity: 2} — 6ms
  PaymentService.charge(customerId: "C-1234", amount: 49.98, cardToken: [REDACTED]) !! PaymentDeclinedError: card declined — 640ms
!! PaymentDeclinedError: card declined — 652ms total
```

--------------------------------

### TypeScript: Read the story with renderIndentedText

Source: https://narrativetrace.ai/

Calls the traced service method and prints the captured trace using renderIndentedText. Notes that in Vitest, every test writes its own trace file.

```TypeScript
service.placeOrder("C-1234", "SKU-KB", 2);

console.log(
  renderIndentedText(context.captureTrace()));

// Vitest: every test writes
// its own trace file.
```
Tokens:
Raw