# Research workflows

The AI Agent conversation helps you inspect a public project, compare its returned pools and ask questions about the evidence. With an authorized connected workspace, you can add a recorded vault snapshot as context and reopen completed research. Returned suggestions require human review; this workflow has no signing or execution tools.

Durable investigations and bounded simulations use the separate [AI agents](/guides/agents) and [What-if Research](/guides/research) contracts.

## Discover the exact project

Search by name, ticker, token address or an `https://app.virtuals.io/virtuals/{id}` URL. A name can match several directory records. Select the exact result after reviewing its Virtuals ID, chain and full token address.

The public discovery API is read-only and does not require a workspace session:

| Method and path | Purpose |
| --- | --- |
| `GET /api/liquidity-studio/v2/public/discovery/search?q={query}&page=1` | Search up to 12 directory records per page |
| `GET /api/liquidity-studio/v2/public/discovery/market/{id}` | Retrieve current directory identity and matching provider pool evidence |
| `GET /api/liquidity-studio/v2/public/discovery/capabilities` | Report configured model status and read-only execution capability |

Search accepts 2–200 characters and pages 1–100. Use the returned numeric project ID for market and assistant requests. Directory presence establishes a provider-supplied identity; it is not an endorsement or ownership verification.

The market adapter recognizes Base, Ethereum, Solana and BNB Chain identifiers. Coverage depends on the provider's returned pools and the project's address. Unsupported chains, prelaunch records and empty pool results remain explicit gaps. Adapter support does not imply custody, trading or finalized chain analysis on every recognized chain.

## Understand market evidence

Klineo retrieves the project identity from the Virtuals directory and pool measurements from DEX Screener. It retains exact-chain matches where the selected token is the pool's base asset and removes duplicate pool addresses. Quote-side matches are excluded because their price describes a different asset.

| Field | Interpretation |
| --- | --- |
| Headline price and 24-hour price change | Taken from the returned pool with the largest known reported liquidity |
| Aggregate liquidity and volume | Sum across all returned matching pools when each contributing value is available |
| `retrievedAt` | The time Klineo received the evidence, rather than a provider observation time or finality assertion |
| `null` measurement | Unavailable; it must not be converted to zero |
| Source IDs | References within this particular evidence snapshot |

If every pool lacks liquidity, Klineo does not promote an arbitrary pool to the headline price. A missing amount in a contributing pool keeps the aggregate unavailable. Real zero values remain zero.

Liquidity is reported pool value, not executable trade depth. Volume is activity, not yield. This snapshot does not supply wallet balances, LP ownership, historical price series, executable slippage or holder concentration. For a finalized-chain evidence requirement, use the app's dedicated finalized reader and inspect its chain, block identity and coverage.

## Ask the assistant

Generation requires an interactive user session, selected workspace membership and `ai:generate`. Read endpoints require `ai:read`. A model being configured does not grant a caller permission to invoke it.

The authenticated request is `POST /api/liquidity-studio/v2/workflows/run`:

```json
{
  "projectId": 272,
  "question": "Which returned pools account for this project's liquidity, and what evidence is missing?",
  "history": []
}
```

The numeric ID above is illustrative; discover and review the project's current identity first. Supply `vaultId` only when you intend to include that authorized workspace snapshot. Use the authenticated session and selected organization's `x-klineo-organization-id` header, as with the rest of the workspace API.

Questions accept 3–2,400 characters. `history` contains at most six preceding `{ "question", "answer" }` exchanges. Each previous question is bounded to 2,400 characters and each previous answer to 6,000. Previous conversation is context; the newly retrieved evidence is the factual source.

The server retrieves fresh evidence before generation. Model pool detail is limited to the largest 20 returned matching pools; aggregate metrics still cover all returned matches, and the model receives the coverage disclosure. It returns a structured answer with:

- A headline and explanation.
- Findings with source IDs from the supplied snapshot.
- Proposed next steps for human review.
- Missing evidence and follow-up questions.

The server validates the answer shape and rejects source IDs outside that snapshot. Invalid or truncated model answers fail visibly. Citation and schema checks do not verify every interpretation.

The response includes the completed answer, exact evidence snapshot, `completedAt`, `execution: "READ_ONLY"` and a persistence label. Optional workspace evidence preserves recorded amounts, chain, block and capture time. A vault snapshot and public token may concern different assets or chains; they must not be combined as if they were the same position. Recorded balances are not a current executable allocation.

## Save and reopen completed research

Connected storage saves the answer and its evidence before acknowledging success. `persistence: "SAVED"` identifies this completed record. The loopback demo has no database and labels its research `"SESSION"`.

| Method and path | Purpose |
| --- | --- |
| `GET /api/liquidity-studio/v2/workflows/context` | List available vault context and report storage availability |
| `GET /api/liquidity-studio/v2/workflows/runs?limit=20` | List your completed entries in the current organization |
| `GET /api/liquidity-studio/v2/workflows/runs/{id}` | Restore one immutable answer and its saved evidence |

Use the returned opaque cursor to continue history. Current membership is checked again at storage access. Saved research is scoped to the requesting user and organization, rather than shared automatically with all members. Reopening a `researchRun` link restores the selected completed exchange; it does not restore an entire multi-exchange conversation. A new question retrieves fresh evidence.

This storage layer saves completed exchanges. It does not provide a resumable pending-job conversation or cross-request generation deduplication. An uncertain request may have reached the model even if the browser lost the response. Avoid treating a new submission as a free retry. Production reserves a durable daily model-attempt slot before dispatch; cancellation or uncertainty does not imply a refund or zero provider usage.

The app's JSON export presents the selected answer and evidence in a selectable text panel. Review the snapshot and its included workspace information before sharing it.

## Errors and availability

| Response | Meaning and recovery |
| --- | --- |
| `400` or `413` | Invalid or oversized input; correct the request |
| `401` or `403` | Session or workspace permission issue; reauthenticate or use an authorized workspace |
| `429` | A request, model-attempt or provider limit; follow available retry timing |
| `502` | Provider data or model response could not be accepted |
| `503` | Required model credentials, production attempt controls or saved storage are unavailable |
| `504` | The request deadline expired; inspect available saved history before resubmitting |

The assistant request has a 55-second server deadline. HTTP request rate and concurrency limits are additional controls, rather than guarantees of availability. Market evidence can remain available while AI explanations are unavailable.

## Local development

From the repository root, start the loopback workflow server and frontend in separate terminals:

```sh
npm run dev:workflows
```

```sh
VITE_LIQUIDITY_STUDIO_DEMO_MODE=true npm run dev:web
```

Configure `GEMINI_API_KEY` in the backend environment to enable model answers, then restart the workflow server. `LIQUIDITY_WORKFLOW_MODEL` selects the configured Gemini model. Never put a provider key in a `VITE_` variable or frontend bundle. Without a key, discovery and market reads work while model generation reports its configuration limitation.

The development server accepts expected loopback origins and refuses production mode. Production uses the authenticated V2 backend, configured PostgreSQL persistence and model-attempt controls. Keep environment credentials outside source control.