ResearchTool.py

[SumanthPal]

Issue 4 — Research tools for agent (market/token research)

Area: Backend / Agent tooling
Goal: Give the agent a research toolset so it can fetch and summarize external info (market research, token research, news, protocol docs) and feed results into decisions.

Context

Agonus needs “agent-authored” research so trading decisions aren’t purely reactive to spot price/market conditions; the agent should be able to ask questions about a token, ecosystem, catalysts, risks, and narrative, and get back a structured answer with citations.

---

What “research” should mean (v1)

Research is not price-history fetching (that’s market data); research is “web-grounded retrieval + synthesis” that returns:

• A short summary the agent can use in prompts.
• A set of citations/URLs for auditability and UI display.
• Optional raw snippets/results for debugging.

Market data (OHLCV, volumes, market cap) should come from a dedicated crypto data API (CoinGecko / CoinMarketCap), while Perplexity covers narrative/news/protocol docs. [coinmarketcap](https://coinmarketcap.com/api/)

---

Tool interface (backend)

Define an internal tool interface that agents call:

research(
  query: string,
  recency?: "1d" | "7d" | "30d" | "365d",
  sources?: ("web" | "news" | "docs")[],
  max_results?: number
) -> {
  summary_markdown: string,
  citations: { title: string, url: string, date?: string }[],
  raw_results: unknown,
  provider: "perplexity",
  created_at: string
}

Key design requirement: citations must be first-class in the return type so the system can enforce “no-citation → don’t trust it” behaviors. [docs.perplexity](https://docs.perplexity.ai/api-reference/chat-completions-post)

---

Provider plan (what API to use)

Provider A (required): Perplexity “Chat Completions”

• Endpoint: POST https://api.perplexity.ai/chat/completions (OpenAI Chat Completions style). [docs.perplexity](https://docs.perplexity.ai/api-reference/chat-completions-post)
• Recommended models include Perplexity’s “sonar” family (docs show examples like sonar-deep-research). [docs.perplexity](https://docs.perplexity.ai/api-reference/chat-completions-post)
• Response includes search_results objects (title/url/date) which can be used directly as citations in your structured output. [docs.perplexity](https://docs.perplexity.ai/api-reference/chat-completions-post)

Provider B (optional but strongly recommended): Token market data API

Add a separate “market data” module for OHLCV / historical prices / volume:

• CoinGecko supports live and historical prices via endpoints like /coins/{id}/market_chart, and also supports chart data by token contract address. [coingecko](https://www.coingecko.com/en/api)
• CoinMarketCap provides real-time pricing and historical data including OHLCV endpoints (often plan-dependent). [stackoverflow](https://stackoverflow.com/questions/68091786/how-can-i-get-current-day-ohlcv-hourly-dta-from-the-coin-market-cap-api)

This keeps “facts from numbers” (prices/volumes) distinct from “facts from web” (news/docs), which helps correctness and evaluation. [coingecko](https://www.coingecko.com/en/api)

---

Storage (Postgres)

Add a table to persist research artifacts so agents can reference prior work and you can audit decisions:

agent_research_artifacts

• id (pk)
• agent_id
• created_at
• query (text)
• recency (text/enum)
• provider (text) — perplexity
• summary_markdown (text)
• citations (jsonb array: {title,url,date})
• raw_results (jsonb) (optional; may be large—consider truncation)
• related_tokens (text[] or jsonb) (optional; extracted entities)

Add an index on (agent_id, created_at desc) for fast “recent memory” lookup.

---

Integration into agent flow (when to trigger research)

Implement a minimal heuristic policy (v1):

• Trigger research when:
  • The token is new to the agent (no prior artifacts within N days), or
  • Confidence score is below a threshold, or
  • A trade size is above a threshold (bigger bet → require research), or
  • The agent detects a narrative-driven token category (meme/news-sensitive) and needs recency.
• Cap research frequency per agent (rate limit) to control cost and prevent loops.

---

Security / safety / cost controls (important)

• Add allowlist/denylist rules for sources if needed (e.g., avoid low-quality domains).
• Enforce max tokens / max results / timeouts at the provider layer to avoid runaway costs. [docs.perplexity](https://docs.perplexity.ai/api-reference/chat-completions-post)
• Store API keys only in server-side env vars; never expose to frontend.

---

Acceptance criteria

• Agent can call research(...) and receive {summary_markdown, citations[], raw_results} with provider marked as Perplexity. [docs.perplexity](https://docs.perplexity.ai/api-reference/chat-completions-post)
• Research artifacts are persisted in Postgres and retrievable by agent_id for reuse in later decisions.
• Citations are stored as URL-based objects (not just “ ”) using Perplexity search_results. [docs.github](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
• A basic trigger policy exists and is documented (even if heuristic-based).
• (Optional) A separate market-data module exists using CoinGecko or CoinMarketCap for OHLCV/history, not via Perplexity. [coinmarketcap](https://coinmarketcap.com/api/)