in reviewhumanPR #320Transport

Stellar Compliance AI: add REDECO compliance-agent A2A integration with fault and fail-closed tests

Stellar Compliance AI prepares answers to REDECO consumer complaints (CONDUSEF, Mexico) for a human compliance officer at a non-bank lender.

Author

Status
In review
Opened on
Nov 8
Branch
integration/stellar-redeco-compliance

Description

The pitch.

## Summary
Stellar Compliance AI prepares answers to REDECO consumer complaints (CONDUSEF, Mexico) for a human compliance officer at a non-bank lender. It reads the regulator portal, opens one case per complaint, links folios the client mistyped, tracks the portal's business-day counter ("6 de 10"), asks the client only for what is missing, and drafts answers in which every claim quotes the client. It never files; the officer approves and files.

This PR adds a Lab integration in `examples/integrations/stellar-redeco/`: an adapter role that drives the agent over A2A, three Town fixtures (portal, client, officer), two scenarios with injected faults, two validators, a verify wrapper, and a CI-safe test.

## Integration
- **Subject:** [`isaisrz/stellar-redeco-agent`](https://github.com/isaisrz/stellar-redeco-agent), hosted separately. It is the deterministic core of our production agent, with synthetic data only (the production deployment is private).
- **Interface:** A2A. The agent card is read at `/.well-known/agent-card.json`. Each input is sent with `message/send` as one JSON event (`portal_snapshot`, `client_message`, `tick`, `officer_approval`), with one `contextId` per run. The agent replies with a completed task whose text artifact is `{"actions": [...]}`.
- **Adapter (`redeco_agent` role):** records every input and action as attributed events. It delivers `request_evidence` to the client, and `draft_ready` and `blocked` to the officer. Any action that tries to file is recorded as `agent_attempted_filing` and never performed.
- **Fixtures:** the portal, client and officer are Town scripts. The only independently developed participant is the agent.

## Reproduce
- Town commit: `6f9a7c0` (current `main`), evaluator `lab-0.2.6`, seed 42.
- Agent: `stellar-redeco-agent` `25ca893` (v0.1.1). Baseline: `f84f4cd` (v0.1.0).

```bash
git clone https://github.com/isaisrz/stellar-redeco-agent && cd stellar-redeco-agent && git checkout 25ca893
python3 -m venv .venv && . .venv/bin/activate && pip install -e '.[dev]' && pytest -q
stellar-redeco-agent serve --port 8950      # leave running

# in this repo
python3 -m venv .venv && . .venv/bin/activate && pip install -e '.[dev]'
nandatown run examples/integrations/stellar-redeco/redeco_compliance.yaml --out runs
nandatown run examples/integrations/stellar-redeco/redeco_portal_down.yaml --out runs
python examples/integrations/stellar-redeco/verify_bundle.py runs/<run id>
python -m pytest -q tests/test_example_stellar_redeco.py      # no agent needed
```
`REDECO_AGENT_URL` overrides the agent URL.

## Results and limitations
The `redeco_compliance` scenario duplicates the portal snapshot and drops the client's first answer. The table shows expected vs observed for each run:

| Run | Expected | Observed | Bundle fingerprint |
|---|---|---|---|
| Agent v0.1.0 | all 8 stages pass | **FAILED** at `grounded_drafts`: no draft for complaint `91058` | `sha256:8cfca0ba…032b5d` |
| Agent v0.1.1 | all 8 stages pass | **PASSED**: `agent_reachable`, `intake_once`, `typo_linked`, `portal_counter`, `lost_message_recovered`, `grounded_drafts`, `human_gate`, `filed_on_time` | `sha256:d69ceeb8…1b5a51` |
| Portal down (boundary) | escalation with reason, owner and next action; no all-clear | **PASSED** (`fail_closed`) | `sha256:5f754c35…9854f` |
| Agent not running | nothing passes | **INCOMPLETE**: every judged stage inconclusive | `sha256:3349d13c…2b23d` |

**Useful failure:** Town found a real agent defect that the agent's own unit tests missed. v0.1.0 always cited "the number that made the collection call". When a complaint did not have one, that citation could never be grounded, so the agent blocked the case instead of drafting it. v0.1.1 cites only what the draft uses and adds a regression test. All four bundles verify with `verify_bundle.py`.

**Compatibility shown:**
- The agent's A2A card and `message/send` work from Town (`nandatown a2a test` passes).
- Its state survives Town's duplicate and drop fa

…

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/320/head:pr-320
git checkout pr-320