Panda Agent

Panda Agent is the evidence-policy checker for PandaSI. It reads one JSON packet about a BNB Smart Chain token and returns either RESEARCH or ABSTAIN. A passing result means the packet is complete enough to keep studying. It does not authorize a trade, a signature, or a transfer.

The program in this repository is deterministic. It uses the Python standard library only. It does not open a network connection, does not hold a key, and does not call a remote model. execution_authorized is false on every path, including a clean fixture and a broken file.

python panda_agent.py
python panda_agent.py --input example_missing_evidence.json
python -m unittest -v

RESEARCH is the name of an empty block list. Every schema check, clock, numeric gate, required check, and veto passed. The summary string is fixed:

Prototype checks passed; continue research. No execution is authorized.

ABSTAIN means at least one blocked reason was recorded. Missing data, a stale clock, a failed type, a breached gate, or a veto all take this path. The summary string is also fixed:

Missing, invalid or vetoed evidence blocks further action.

Neither word is a price view, a safety certificate, or an instruction to buy or sell. The same two uncertainty lines and the same two invalidation lines are attached to both decisions:

Urgency in a surrounding note, a ticker, or a comment inside the packet cannot change the outcome. The checker never reads a field named metadata. In the tests, setting source_verified to false still abstains when a metadata string tells the program to ignore its rules.

evaluate(packet, now=None) is the whole policy. now defaults to the current UTC time, which lets tests freeze the clock. main loads JSON from --input or builds the fictional jade fixture, prints indented JSON, and exits. A missing file or broken JSON becomes an abstention whose reason starts with Input error:.

flowchart TD
  packet[Evidence packet] --> schema{Object, chain 56, address, evidence ids}
  schema -->|fail| abstain[ABSTAIN]
  schema --> typed{Numbers finite and checks boolean}
  typed -->|fail| abstain
  typed --> clocks{Clocks inside their windows}
  clocks -->|fail| abstain
  clocks --> gates{Gates, required trues, and vetoes}
  gates -->|fail| abstain
  gates --> research[RESEARCH]
  research --> locked[execution_authorized is false]
  abstain --> locked

Reasons accumulate. One bad field does not hide the next. An invalid address and a stale market clock are both listed. Threshold comparisons run only after every numeric field is a finite number greater than or equal to zero, so a negative liquidity value is reported as invalid rather than as "below the floor."

A value that is not a JSON object returns immediately with Packet must be an object, an empty evidence list, a null token key, and coverage 0. Every JSON object continues through the remaining checks.

A token is an integer chain plus a contract address. The ticker is not an identity.

token_key is chain_id, a colon, and token_address when the address string is non-empty. Otherwise token_key is null. chain_id must be the integer 56. token_address must be 0x followed by exactly 40 hexadecimal digits.

The chain test uses exact integer type, so a boolean or a float such as 56.0 is an unsupported chain. The address test is a full match: the 0x prefix, forty hex digits, and nothing else. Mixed case is accepted. There is no checksum step. token_key is still formed for a non-empty address that fails the pattern, so the key is a label, not evidence that the address passed.

decision is RESEARCH when the blocked-reason list is empty, and ABSTAIN otherwise. execution_authorized is false on both results.

Rates in the packet are basis points. One basis point is one hundredth of one percent.

$$ 1,\mathrm{bp} = 10^{-4} = 0.01% \qquad x_{%} = \frac{x_{\mathrm{bps}}}{100} $$

So 100 bps is 1 percent, and the tax ceiling of 500 bps is 5 percent. The code compares the raw basis-point numbers. It does not convert them before the test.

Both observation fields must be timezone-aware ISO-8601 strings. A trailing Z is read as UTC. A naive timestamp, a number, or a missing key is invalid.

$$ a(t) = t_{\mathrm{now}} - t $$

$$ 0 \le a(t_{\mathrm{market}}) \le 60 \qquad 0 \le a(t_{\mathrm{security}}) \le 300 $$

The market window is one minute. The security window is five minutes. Age is measured in seconds. The boundary is inclusive: a market observation exactly 60 seconds old still passes, and 61 seconds abstains. A timestamp one second in the future abstains. The tests pin those three edges.

Coverage is a separate count: how many required keys are not null, rounded to three decimal places. It is not a trust score, a probability, or a weighted rating.

The required keys are the seven numeric fields, the six boolean fields, market_observed_at, security_observed_at, evidence_ids, chain_id, and token_address. That set has 18 keys. Coverage is the number of those keys that are not null, divided by 18, then rounded to three decimal places.

A present value can still be the wrong type, a failing check, or a veto. A fully present packet that trips a veto has coverage 1.0 and decision ABSTAIN. The incomplete sample has sixteen of the eighteen keys present, so its coverage is 0.889.

These comparisons run only when all seven numbers are finite and non-negative. A boolean, NaN, infinity, a string, or a negative value is Missing or invalid <field> and skips this block.

$$ L \ge 100000 \qquad 0 < q \le 100 \qquad I \le 100 \qquad S \le 100 \qquad \max(\tau_{\mathrm{buy}}, \tau_{\mathrm{sell}}) \le 500 \qquad H_{10} \le 40 $$

An order of 0 fails, and an order of 100 passes. Holder concentration of 40 passes, and 40.1 abstains. Impact, slippage, and tax use the same edge: the limit itself passes, and one basis point past it abstains. Liquidity of 99999 is below the floor.

JSON true and false are the only accepted boolean spellings. The string "true" fails the type check. JSON null also fails that check, and it lowers coverage because null is absent. A required check that is false is recorded again as a failed check. A veto records a reason only when the value is true; a missing veto field has already failed the type check.

Removing any single key from a complete packet is enough to abstain. The unit tests pop each key in turn and expect ABSTAIN.

python panda_agent.py builds this packet with both clocks set to the current UTC time. The address is forty ones. It is a fixture, not a listed contract. Evidence id: fixture:jade.

A run of that command returns:

The saved copy of that shape is example_output.json.

example_missing_evidence.json keeps the same identity and the same market numbers, then sets source_verified and sell_simulation_passed to null. Its clocks are fixed at 2026-10-16T17:33:25.657328+00:00. After the one-minute market window and the five-minute security window, both stamps are stale. A run on 22 October 2026 produced:

Coverage stays 0.889 on later runs because it counts nulls, not age. The stale reasons remain while those two timestamps sit outside the windows. A passing packet needs the two checks set back to true and both clocks moved to the present. The program does not fill in the missing checks.

From this directory, with Python 3.9 or newer:

python panda_agent.py
python panda_agent.py --input example_missing_evidence.json
python -m unittest -v

No third-party package is imported. argparse, json, math, re, datetime, and pathlib are the whole runtime.

SYSTEM_PROMPT.md describes a later research companion. That note is not imported, parsed, or enforced here. Where the two disagree, the running policy is panda_agent.py.

The research tools named in the design note are get_token_identity, get_market_snapshot, get_liquidity_quote, get_contract_permissions, get_holder_distribution, get_sell_simulation, and get_source_provenance. They are not implemented in this repository. The interface here is the offline packet above.

Portfolio limits, a live quote, and an exact order intent are named in the result's uncertainty list because this prototype does not check them. Passing the eighteen fields is not a statement that those later gates would pass.

The mark, wordmark, and lockup are the PandaSI drawings used above.