Dexter JP Architecture: AI Financial Agent for TSE

Dexter JP is an autonomous, financial-research AI agent tailored specifically for the Japanese stock market (~3,800 listed equities on the Tokyo Stock Exchange). Built upon TypeScript and executed via the high-performance Bun runtime environment, Dexter JP acts as a specialized fork of the US-focused virattt/dexter engine. Rather than functioning as a standard financial data retriever that executes single API calls, Dexter JP establishes an autonomous reasoning loop powered by LangChain. Upon receiving a high-level natural language prompt—such as a request to analyze competitive dynamics, evaluate balance sheet quality, or perform a discounted cash flow (DCF) valuation—Dexter JP constructs a multi-step execution plan, invokes heterogeneous financial data tools in parallel, validates retrieved data against underlying corporate narratives, and generates structured analytical reports without requiring human intervention.

Autonomous Agent Loop & System Architecture

Dexter JP executes an autonomous agentic loop powered by LangChain that receives natural language queries, formulates structured execution plans, and calls specialized data tools in parallel. The architecture dynamically retrieves financial statements, validates cross-source consistency, compresses historical context, and synthesizes multi-page corporate analysis reports without requiring manual human oversight.

The system architecture moves beyond traditional, deterministic tool-calling pipelines by completely decoupling request handling into plan generation, parallel tool execution, autonomous output validation, and stateful context compression. When a user submits a financial query to Dexter JP, the core agent engine does not execute a simple static database lookup. Instead, it initializes an iterative decision loop designed to navigate the nuanced data structures of Japanese regulatory frameworks and market feeds.

The operational data processing pipeline follows a rigorous architectural flow:

• User Input Ingestion & Ingress Control: Accepts natural language prompts through the terminal command-line interface (CLI), persistent multi-channel messaging socket connections, or dedicated HTTP webhooks in both English and Japanese.
• Agent Reasoning & Plan Formulation: The core LangChain reasoning engine evaluates the incoming query against active, user-injected system rules (defined inside .dexter/RULES.md) and short-term session memory. It formulates a structured, step-by-step investigation plan identifying necessary data points across formal regulatory disclosures, earnings announcements, market price histories, and web-based contextual feeds.
• Tool Selection & Concurrent Orchestration: The agent loop dynamically triggers one or more underlying data integration modules. Depending on query complexity, the agent invokes specialized sub-tools directly or dispatches complex financial analytical requests to the internal get_financials meta-tool.
• Sub-Tool Execution Suite:
  • get_financials (Meta-Tool): Analyzes queries using an internal sub-routing LLM to execute parallel dispatch calls to get_financial_statements, get_company_info, get_key_ratios, get_analysis, and get_earnings.
  • read_filings: Extracts structured text blocks and disclosures from annual securities reports (Yukashoken Hokokusho via EDINET), quarterly reports, and large shareholding filings (>5% ownership change events).
  • company_screener: Screens over 3,800 listed Japanese companies across all 33 Tokyo Stock Exchange industry sectors using more than 100 quantitative metric parameters.
  • get_stock_price: Pulls official Tokyo Stock Exchange daily and historical OHLC pricing, volume, and adjusted valuation multiples via the J-Quants V2 API.
  • web_search / browser / skills: Executes broader external search fallback chains using Exa, Perplexity, or Tavily search APIs to capture recent news, market rumors, or macroeconomic developments.
• Autonomous Verification & Verification Loop: The agent loop systematically reviews returned tool payloads to identify internal contradictions—such as discrepancies between quantitative income statement numbers and qualitative management discussion notes in securities filings. If missing data or logical gaps are detected, the loop self-corrects and issues targeted secondary tool calls.
• Context Compression Subsystem: In extended research sessions yielding thousands of raw financial data tokens, an auxiliary lightweight model pass automatically condenses historical tool outputs into state summaries. Critical balance sheet figures, cash flow metrics, and analytical findings are retained while clearing redundant token overhead within the context window.
• Structured Report Synthesis: The final agent loop aggregates all verified quantitative tables, qualitative risk factors, competitive peer comparisons, and macroeconomic considerations into a clear, publication-ready markdown research report.

Comparative Architecture: Dexter JP vs. Financial Framework Alternatives

Dexter JP differs from standard US-centric financial agents by swapping SEC filings and USD macroeconomic baselines for EDINET disclosures, TDNet earnings, and official Tokyo Stock Exchange J-Quants market data. Optimized for 3,800 listed Japanese equities, it replaces generic API wrappers with localized DCF valuation skills and multi-channel messaging integrations.

To evaluate where Dexter JP sits within the broader financial software engineering ecosystem, the following matrix compares its technical features against its upstream parent repository (Original US Dexter) and standard generic LLM wrappers connected to traditional financial APIs.

Core Features & System Subsystem Deep-Dives

Dexter JP’s core architecture combines four specialized subsystems: an internal get_financials meta-tool for parallel API routing, a Japanese market-calibrated DCF valuation engine, localized markdown instruction enforcement (RULES.md), and Claude Agent SDK integration with automated context compression, ensuring comprehensive analytical depth while preventing context window exhaustion during complex research workflows.

1. Meta-Tool Architecture (get_financials)

In conventional AI agent implementations, retrieving complete financial datasets requires the main agent loop to execute multiple distinct API requests sequentially. This sequential pattern creates major latency bottlenecks and consumes unnecessary reasoning cycles. Dexter JP overcomes this structural inefficiency through its nested Meta-Tool Architecture.

The get_financials tool does not simply wrap a single API endpoint. Instead, it functions as an internal routing sub-agent equipped with its own lightweight LLM instance. When the main agent requests a complete financial audit of a listed company (such as benchmarking Toyota Motor Corporation against its global and domestic peers):

1. The request is passed directly into the get_financials meta-tool container.
2. The meta-tool’s internal router parses the research objective and identifies required quantitative endpoints.
3. It fires asynchronous, concurrent requests across get_financial_statements, get_company_info, get_key_ratios, get_analysis, and get_earnings.
4. It aggregates, normalizes, and validates the raw JSON responses before delivering a consolidated financial payload back to the primary agent loop.

2. Localized Financial Skills (DCF Engine)

Valuation models developed for US capital markets produce misleading results when applied directly to Japanese corporate structures without adjusting for distinct macroeconomic parameters, corporate governance rules, and accounting practices. Dexter JP encodes domain-specific analysis patterns directly into structured SKILL.md definitions.

Its native Discounted Cash Flow (DCF) skill is explicitly tuned for the Japanese market environment:

• WACC Baseline Calibration: Replaces US Treasury rate baselines with Japanese Government Bond (JGB) yield figures (~1.0% long-term benchmark baseline) for risk-free rate calculations.
• Capital Efficiency & PBR Directive Tracking: Incorporates explicit risk and cost-of-equity adjustments by assessing corporate adherence to the Tokyo Stock Exchange’s mandate urging listed companies with a Price-to-Book Ratio (PBR) below 1.0x to disclose action plans for capital cost improvement.
• Currency Denomination Alignment: Strictly enforces Japanese Yen (JPY) cash flow projections and financial statement extraction, preventing cross-currency inflation or conversion skews.

3. Custom Injected Research Rules (.dexter/RULES.md)

Dexter JP enables investment teams and financial analysts to inject specific analytical directives directly into the agent’s core prompt hierarchy through system markdown files. By customizing .dexter/RULES.md, engineering leads can enforce standardized investment methodologies across all research workflows without modifying source code.

An example setup for a .dexter/RULES.md configuration file:

# Corporate Analysis Standard Operating Procedure

- **Peer Benchmarking:** Always compare target company metrics against at least 5 direct TSE sector competitors.
- **Unit Formatting:** Always present quantitative financial tables in JPY Millions (百万円).
- **Value Investing Filter:** Flag any company that fails the criteria: ROE > 10% AND PBR < 1.5.
- **Risk Assessment Protocol:** Mandate the extraction of management discussion items from the latest annual securities report (有価証券報告書) regarding foreign exchange rate sensitivity and raw material cost inflation.

Executing the /rules command within the interactive CLI dynamically lists all active system directives currently compiled into memory.

4. Claude Agent SDK Execution Mode

In addition to its default LangChain runtime environment, Dexter JP offers deep native integration with @anthropic-ai/claude-agent-sdk. Engaging this operational mode delegates the agent’s reasoning loop directly to Anthropic’s optimized agent infrastructure.

Key operational characteristics of the Claude Agent SDK execution mode include:

• Decoupled Authentication Architecture: The application avoids storing or asking for plaintext user API credentials directly. Instead, key resolution flows through environment settings, using active Claude Code developer logins, CLAUDE_CODE_OAUTH_TOKEN, or an environment-level ANTHROPIC_API_KEY.
• Dynamic Model Switching: Language model backends can be dynamically toggled inside the CLI via the /model command interface to switch between available models like claude-fable-5, claude-opus-4-8, or claude-sonnet-4-6.
• Passthrough Tool Registration: Dexter JP presents its complete suite of Japanese financial data integration tools directly to the SDK as native passthrough tools, eliminating secondary internal routing overhead.
• Fail-Loud Metered Safeguards: If a metered environment variable (such as ANTHROPIC_API_KEY, CLAUDE_CODE_USE_BEDROCK, or CLAUDE_CODE_USE_VERTEX) is present, the runtime halts immediately to prevent unmonitored API expenditure. Users must explicitly opt in by exporting DEXTER_AGENT_SDK_ALLOW_METERED=1.
• Session Spending Caps: Strict financial expenditure boundaries can be enforced by specifying a maximum cost limit in USD using DEXTER_AGENT_SDK_MAX_BUDGET_USD.

Multi-Channel Messaging Gateway Architecture

Dexter JP features a unified multi-channel messaging gateway that enables concurrent deployment across Slack, Discord, LINE, and WhatsApp messaging environments. Operating through persistent WebSocket connections or dedicated HTTP webhooks, the gateway provides enterprise team access to autonomous financial research agents with native threaded responses and session tracking.

Beyond terminal usage, Dexter JP can be deployed as an enterprise gateway service executed via bun run gateway. This background gateway process continuously manages real-time messaging interactions across four major communication platforms simultaneously without requiring separate application deployments.

• Slack Integration Architecture: Connects over Slack’s Socket Mode protocol using persistent WebSockets. This eliminates the need for public inbound HTTP endpoints or reverse proxies.
  • Required credentials: SLACK_BOT_TOKEN (prefixed with xoxb-) and SLACK_APP_TOKEN (prefixed with xapp-).
  • Operational behavior: Responds directly within direct messages and automatically initiates structured threads when mentioned in group channels.
• Discord Integration Architecture: Connects directly to the Discord Gateway API via persistent WebSocket connections.
  • Required credential: DISCORD_BOT_TOKEN with the Message Content Intent flag enabled in the Discord Developer Portal.
  • Operational behavior: Listens for direct messages and creates focused discussion threads when tagged via @BotName.
• LINE Integration Architecture: Operates using an HTTP Webhook architecture tailored to the LINE Messaging API.
  • Required credentials: LINE_CHANNEL_SECRET and LINE_CHANNEL_ACCESS_TOKEN, bound by default to local port WEBHOOK_PORT=3000.
  • Deployment requirement: Demands a publicly accessible HTTPS URL route (e.g., https://domain.com/webhook/line). Must run on persistent server infrastructure—ephemeral serverless environments like Vercel or AWS Lambda are unsupported.
• WhatsApp Integration Architecture: Uses the Baileys WebSocket library to maintain direct socket communication with WhatsApp infrastructure, authenticated via initial terminal QR code scanning.

Installation, Configuration & Production Setup Recipes

Setting up Dexter JP in production requires installing the Bun JavaScript runtime, cloning the repository, installing dependencies, and configuring environment variables in .env. Key prerequisites include an EDINET DB API key for financial disclosures, an optional J-Quants V2 key for daily OHLC prices, and a supported LLM provider API key.

1. Base System Requirements & Installation

Verify that Bun (v1.0.0 or higher) is installed on the host system. Clone the GitHub repository and install project dependencies:

# Clone repository
git clone https://github.com/edinetdb/dexter-jp.git
cd dexter-jp

# Install dependencies using Bun
bun install

# Create localized environment configuration from template
cp env.example .env

2. Environment Configuration (.env)

Configure required and optional service credentials within the .env configuration file:

# === REQUIRED: LLM PROVIDERS (At least one key required) ===
OPENAI_API_KEY=sk-proj-...          # OpenAI API key
ANTHROPIC_API_KEY=sk-ant-...        # Anthropic Claude API key
GOOGLE_API_KEY=AIzaSy...             # Google Gemini API key
XAI_API_KEY=xai-...                  # xAI Grok API key
OPENROUTER_API_KEY=sk-or-...         # OpenRouter API key
OLLAMA_BASE_URL=http://127.0.0.1:11434 # Local Ollama instance URL

# === REQUIRED: JAPANESE EQUITY DATA ENGINE ===
EDINETDB_API_KEY=edb_...            # Obtained from edinetdb.jp (Free tier available)

# === OPTIONAL: OFFICIAL TSE STOCK PRICE DATA ===
JQUANTS_API_KEY=...                 # Enables get_stock_price tool via jpx-jquants.com

# === OPTIONAL: WEB SEARCH FALLBACKS ===
# Priority order: Exa -> Perplexity -> Tavily
EXASEARCH_API_KEY=...
PERPLEXITY_API_KEY=...
TAVILY_API_KEY=...

# === OPTIONAL: SOCIAL DATA INTEGRATION ===
X_BEARER_TOKEN=AAAA...

# === CLAUDE AGENT SDK CONTROLS ===
DEXTER_AGENT_SDK_ALLOW_METERED=1     # Set to 1 to explicitly permit paid API utilization
DEXTER_AGENT_SDK_MAX_BUDGET_USD=5.00  # Sets spending cap per session in USD

# === OPTIONAL: MESSAGING GATEWAY CONNECTIONS ===
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

DISCORD_BOT_TOKEN=MTQ4...

LINE_CHANNEL_SECRET=a1b2c3...
LINE_CHANNEL_ACCESS_TOKEN=token...
WEBHOOK_PORT=3000

3. Running the CLI Interface

To initiate an interactive financial research session from the command line:

# Start CLI interactive prompt
bun run start

While inside the CLI session, users can adjust agent operational behavior using built-in interactive commands:

# Display active system rules loaded from .dexter/RULES.md
/rules

# Change active LLM provider or switch execution mode to Claude Agent SDK
/model

4. Executing Practical Research Prompts

Dexter JP processes both quick financial lookups and multi-phase research workflows:

# Multi-Stage Autonomous Research Workflow
"Analyze Toyota's overall competitiveness. Synthesize quantitative financial statements, disclosures from their annual securities report, and latest TDNet earnings filings into a comprehensive report."

# Strategic Comparative Analysis
"Compare Sony and Nintendo as long-term investment targets. Evaluate financial health, profitability, sales growth, and strategic risk factors before delivering a final recommendation."

# Fundamental Stock Screening & Deep Dive
"Screen for Japanese companies with ROE > 15% and Equity Ratio > 50%. Deep-dive into the balance sheet strength and business risks of the top 3 candidates."

# Historical Multi-Year Trend Analysis
"Show Nintendo's financial statements and metrics trend over the last 5 years."

5. Launching the Multi-Channel Gateway Server

To launch the persistent background gateway serving Slack, Discord, LINE, and WhatsApp messaging clients simultaneously:

# Start background omnichannel gateway
bun run gateway

Common Pitfalls, Safety & Troubleshooting

Deploying Dexter JP safely requires mitigating specific operational pitfalls, such as unexpected API cost spikes in Claude Agent SDK mode, serverless timeout failures during LINE webhook processing, missing J-Quants pricing keys, and context window exhaustion during multi-year disclosure extraction. Correct configuration settings and persistent hosting infrastructure eliminate these execution errors.

1. Claude Agent SDK Unintended Metered Billing Safeguard Block

Problem: Launching Dexter JP in Claude Agent SDK mode while ANTHROPIC_API_KEY or cloud provider credentials are present causes the runtime engine to immediately halt execution with a safeguard error.

Cause: Dexter JP incorporates a hard fail-loud safety check designed to block unintended financial charges when executing agent loops inside SDK environments.

Solution: To permit paid API usage, add DEXTER_AGENT_SDK_ALLOW_METERED=1 to your .env environment file. To prevent cost overruns, establish a session spending limit by setting DEXTER_AGENT_SDK_MAX_BUDGET_USD=5.00.

2. LINE Webhook Failure on Serverless Platforms

Problem: Hosting the LINE Gateway module on serverless cloud platforms like Vercel, AWS Lambda, or Netlify causes dropped webhooks, duplicate responses, or execution timeout errors.

Cause: The LINE Messaging API relies on standard HTTP webhooks that expect persistent, low-latency event handlers. Ephemeral serverless workers freeze or shut down background tasks, interrupting active HTTP listeners and WebSocket tasks.

Solution: Run bun run gateway on persistent server platforms such as Railway, Fly.io, Render (as a Background Worker), Google Cloud Run (configured with min-instances=1), or dedicated virtual private servers (VPS). Ensure local port WEBHOOK_PORT=3000 is exposed through a secure HTTPS reverse proxy.

3. Missing Market Price Data in Financial Valuation Reports

Problem: The research agent successfully pulls fundamental financial statements but reports missing valuation metrics, such as daily share prices, PE ratios, or historical market cap figures.

Cause: While EDINET DB provides regulatory financial filings, real-time and historical OHLC market price feeds require integration with official Tokyo Stock Exchange data via J-Quants V2.

Solution: Sign up for a developer account at jpx-jquants.com, generate an API key, and populate the JQUANTS_API_KEY variable in your .env file to enable the get_stock_price tool.

4. Context Window Overflow During Multi-Year Historical Audits

Problem: The LLM hits context window token limitations when processing raw securities reports across several operating years for multiple target entities.

Cause: Japanese Annual Securities Reports (Yukashoken Hokokusho) contain extensive qualitative commentary that can quickly consume available context window capacity.

Solution: Verify that a fast auxiliary model key is configured in .env (such as OPENAI_API_KEY or ANTHROPIC_API_KEY). This allows Dexter JP to run automated secondary compression passes on long filings before passing summarized context to the main reasoning loop.

5. Financial Disclaimer & Usage Constraints

Dexter JP is explicitly built for educational, research, and technical evaluation purposes only. It is not licensed investment advisory software, nor does it generate personalized financial, legal, or tax recommendations. Reports generated by autonomous LLM loops may contain inaccuracies, hallucinations, or parsing errors from underlying regulatory disclosures. Users assume full operational risk and must consult qualified investment professionals before committing capital based on automated agent outputs.

Adoption Decision Matrix: When to Use vs. When NOT to Use

Dexter JP is ideal for institutional research, multi-company fundamental screening, and custom investment modeling across Tokyo Stock Exchange equities. However, it is explicitly unsuitable for high-frequency algorithmic trading, automated execution routing, serverless cloud host deployments, or non-Japanese financial markets that rely on SEC regulatory filing frameworks and Western accounting standards.