# agentuity/agent-hedgefund architecture

> Architecture diagram of the GitHub repository agentuity/agent-hedgefund, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agentuity/agent-hedgefund
- Repository: https://github.com/agentuity/agent-hedgefund

## Overview

1. **What this repo is**
   - This is a Python 3.10+ trading agent built for **Agentuity** and orchestrated with **LangGraph**.
   - The system’s job is to turn a natural-language market/trading question into a concrete trading recommendation, with portfolio context, risk checks, and an action table.

2. **Primary runtime and deployment boundary**
   - `agentuity.yaml`, `main.py`, and `server.py` are the deployment/serve boundary.
   - The agent is meant to run locally via `agentuity dev` and in production on Agentuity’s hosted runtime.
   - The repo also includes CI/deploy automation under `.github/workflows/agentuity.yaml`.

3. **Top-level architecture**
   - The code is split into four clear layers:
     - `models/` for typed data contracts
     - `nodes/` for the LangGraph workflow steps
     - `services/` for domain logic and orchestration helpers
     - `tools/` for data acquisition and analysis utilities
   - This separation is the main architectural boundary: workflow composition in nodes, business logic in services, external/algorithmic work in tools.

4. **Workflow orchestration**
   - `agents/hedge_fund/agent.py` is the likely composition root that wires the graph together.
   - The documented flow is: **query parsing → asset search → technical analysis → risk assessment → portfolio decisions → response generation**.
   - `nodes/workflow.py`, `nodes/routing.py`, and the other node modules represent the graph stages and branching logic.

5. **Input understanding and routing**
   - `nodes/parsing.py` plus `tools/action_parser.py` and the models in `models/user_context.py` and `models/action.py` handle interpretation of the user request.
   - This layer extracts intent such as “buy”, “sell”, “hold”, position context, and risk signals before any market analysis happens.
   - `nodes/routing.py` then decides which downstream path to take based on the parsed intent and complexity of the request.

6. **Market asset discovery**
   - `nodes/search.py` and `services/asset_search_service.py` connect the request to a tradable asset or symbol.
   - `tools/asset_search.py` is the lower-level lookup utility.
   - This is the boundary where user language is normalized into concrete market instruments.

7. **Technical analysis subsystem**
   - `services/technical_analyst.py` and `tools/technical/` implement the quantitative market-analysis side.
   - The technical toolset is split into:
     - `data_fetcher.py` for pulling live price/market data
     - `indicators.py` for indicator computation
     - `signal_interpreter.py` for translating indicator values into directional signals
     - `manager.py` for coordinating technical analysis
   - The README indicates the main indicators are **RSI, MACD, and EMA**.

8. **Sentiment and macro analysis subsystem**
   - `services/market_sentiment_analyst.py` and `tools/sentiment/` provide non-price-based context.
   - The sentiment tools are decomposed into `news_analyzer.py`, `economic_analyzer.py`, and `fear_greed_analyzer.py`, coordinated by `tools/sentiment/manager.py`.
   - External data sources are environment-backed, including **NewsAPI** and **FRED**, which feed this layer.

9. **Risk and portfolio decision engine**
   - `nodes/risk_management.py`, `services/risk_manager_service.py`, and `services/trade_decision_service.py` form the decision boundary.
   - `nodes/portfolio_manager.py` and `models/portfolio_decision.py` represent the portfolio/action output.
   - This layer combines analysis results with user holdings and risk constraints to produce concrete outcomes like **BUY / SELL / HOLD**, position sizing, and risk recommendations.

10. **Response generation and formatting**
    - `nodes/llm_response.py` and `services/response_formatter_service.py` turn the internal decision into the final user-facing answer.
    - The output is designed to be actionable, often including trade tables, entry/exit levels, stop losses, and sizing guidance.
    - `resources/` likely holds prompt or template assets used during this final formatting stage.

11. **Data and type contracts**
    - The models in `agents/hedge_fund/models/` define the structured data passed between layers:
      - `workflow.py` for graph/state shape
      - `user_context.py` for user and portfolio context
      - `action.py` for parsed intent
      - `portfolio_decision.py` for final recommendation data
    - These contracts are important because the graph is stateful and each node passes structured state forward.

12. **End-to-end data flow**
    - A request enters through the Agentuity-served endpoint, is parsed into structured intent, resolved to an asset, enriched with technical and sentiment data, checked against risk rules, converted into a portfolio decision, and finally formatted into a natural-language recommendation.
    - The main external dependencies that materially shape the architecture are **Agentuity** for hosting/orchestration and live market/news APIs for data.

13. **How to think about the system on a diagram**
    - Draw the system as a layered pipeline with a central LangGraph orchestrator.
    - Put API ingestion at the top, then parsing/routing, then two parallel analysis branches (technical + sentiment), then risk/decision synthesis, then response formatting.
    - Show external services only on the analysis side: market data, news, and macro/fear-greed inputs feeding into the analytical tools.

Main entry points: [`agents/hedge_fund/nodes/analysis.py`](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/analysis.py) (Analysis), [`agents/hedge_fund/tools/technical/manager.py`](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/technical/manager.py) (Tech manager), [`agents/hedge_fund/tools/sentiment/manager.py`](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/sentiment/manager.py) (Sentiment manager), [`agents/hedge_fund/agent.py`](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/agent.py) (Agent root)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime boundary"]
  node_agentuity_yaml["Agentuity<br/>deployment config<br/>[agentuity.yaml]"]
  node_main_py["Main<br/>entrypoint<br/>[main.py]"]
  node_server_py["Server<br/>serve layer<br/>[server.py]"]
end

subgraph group_orchestration["Workflow orchestration"]
  node_agent_root["Agent root<br/>composition root<br/>[agent.py]"]
  node_workflow_model["Workflow state<br/>state contract<br/>[workflow.py]"]
  node_parsing_node["Parsing<br/>workflow node<br/>[parsing.py]"]
  node_routing_node["Routing<br/>workflow node<br/>[routing.py]"]
  node_search_node["Search<br/>workflow node<br/>[search.py]"]
  node_analysis_node["Analysis<br/>workflow node<br/>[analysis.py]"]
  node_risk_node["Risk<br/>workflow node<br/>[risk_management.py]"]
  node_portfolio_node["Portfolio<br/>workflow node"]
  node_response_node["Response<br/>workflow node<br/>[llm_response.py]"]
end

subgraph group_domain["Domain services"]
  node_controller["Controller<br/>orchestrator service<br/>[controller.py]"]
  node_asset_service["Asset search<br/>domain service"]
  node_technical_service["Technical<br/>domain service"]
  node_sentiment_service["Sentiment<br/>domain service"]
  node_risk_service["Risk manager<br/>domain service"]
  node_decision_service["Decision engine<br/>domain service"]
  node_formatter_service["Formatter<br/>domain service"]
end

subgraph group_analysis["Analysis tools"]
  node_action_parser["Action parser<br/>parser utility<br/>[action_parser.py]"]
  node_asset_search_tool["Asset lookup<br/>lookup utility<br/>[asset_search.py]"]
  node_technical_manager["Tech manager<br/>analysis coordinator<br/>[manager.py]"]
  node_data_fetcher["Market data<br/>data acquisition<br/>[data_fetcher.py]"]
  node_indicators["Indicators<br/>indicator engine<br/>[indicators.py]"]
  node_signal_interpreter["Signal interp<br/>signal translator"]
  node_sentiment_manager["Sentiment manager<br/>analysis coordinator<br/>[manager.py]"]
  node_news_analyzer["News<br/>[news_analyzer.py]"]
  node_economic_analyzer["Macro"]
  node_fear_greed_analyzer["Fear greed<br/>sentiment signal"]
end

node_agentuity_yaml -->|"deploys"| node_main_py
node_agentuity_yaml -->|"serves"| node_server_py
node_main_py -->|"starts"| node_agent_root
node_server_py -->|"routes to"| node_agent_root
node_agent_root -->|"uses state"| node_workflow_model
node_agent_root -->|"wires"| node_parsing_node
node_parsing_node -->|"parses with"| node_action_parser
node_parsing_node -->|"outputs"| node_routing_node
node_routing_node -->|"may branch to"| node_search_node
node_routing_node -->|"may branch to"| node_analysis_node
node_search_node -->|"uses"| node_asset_service
node_asset_service -->|"looks up"| node_asset_search_tool
node_analysis_node -->|"runs"| node_technical_service
node_analysis_node -->|"runs"| node_sentiment_service
node_technical_service -->|"coordinates"| node_technical_manager
node_technical_manager -->|"fetches"| node_data_fetcher
node_technical_manager -->|"computes"| node_indicators
node_technical_manager -->|"interprets"| node_signal_interpreter
node_sentiment_service -->|"coordinates"| node_sentiment_manager
node_sentiment_manager -->|"analyzes"| node_news_analyzer
node_sentiment_manager -->|"analyzes"| node_economic_analyzer
node_sentiment_manager -->|"analyzes"| node_fear_greed_analyzer
node_analysis_node -->|"feeds"| node_risk_node
node_risk_node -->|"checks with"| node_risk_service
node_risk_node -->|"passes"| node_portfolio_node
node_portfolio_node -->|"decides with"| node_decision_service
node_decision_service -->|"hands off to"| node_formatter_service
node_portfolio_node -->|"updates"| node_response_node
node_response_node -->|"formats with"| node_formatter_service
node_formatter_service -->|"returns via"| node_controller

click node_agentuity_yaml "https://github.com/agentuity/agent-hedgefund/blob/main/agentuity.yaml"
click node_main_py "https://github.com/agentuity/agent-hedgefund/blob/main/main.py"
click node_server_py "https://github.com/agentuity/agent-hedgefund/blob/main/server.py"
click node_agent_root "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/agent.py"
click node_workflow_model "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/models/workflow.py"
click node_parsing_node "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/parsing.py"
click node_routing_node "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/routing.py"
click node_search_node "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/search.py"
click node_analysis_node "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/analysis.py"
click node_risk_node "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/risk_management.py"
click node_portfolio_node "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/portfolio_manager.py"
click node_response_node "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/llm_response.py"
click node_controller "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/controller.py"
click node_asset_service "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/asset_search_service.py"
click node_technical_service "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/technical_analyst.py"
click node_sentiment_service "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/market_sentiment_analyst.py"
click node_risk_service "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/risk_manager_service.py"
click node_decision_service "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/trade_decision_service.py"
click node_formatter_service "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/response_formatter_service.py"
click node_action_parser "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/action_parser.py"
click node_asset_search_tool "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/asset_search.py"
click node_technical_manager "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/technical/manager.py"
click node_data_fetcher "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/technical/data_fetcher.py"
click node_indicators "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/technical/indicators.py"
click node_signal_interpreter "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/technical/signal_interpreter.py"
click node_sentiment_manager "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/sentiment/manager.py"
click node_news_analyzer "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/sentiment/news_analyzer.py"
click node_economic_analyzer "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/sentiment/economic_analyzer.py"
click node_fear_greed_analyzer "https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/sentiment/fear_greed_analyzer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agentuity_yaml,node_main_py,node_server_py toneBlue
class node_agent_root,node_workflow_model,node_parsing_node,node_routing_node,node_search_node,node_analysis_node,node_risk_node,node_portfolio_node,node_response_node toneAmber
class node_controller,node_asset_service,node_technical_service,node_sentiment_service,node_risk_service,node_decision_service,node_formatter_service toneMint
class node_action_parser,node_asset_search_tool,node_technical_manager,node_data_fetcher,node_indicators,node_signal_interpreter,node_sentiment_manager,node_news_analyzer,node_economic_analyzer,node_fear_greed_analyzer toneRose
```

## Components

### Runtime boundary

Agentuity entrypoints and deployment wiring

- [Agentuity](https://github.com/agentuity/agent-hedgefund/blob/main/agentuity.yaml): deployment config · Hosted runtime and local dev configuration · `agentuity.yaml`
- [Main](https://github.com/agentuity/agent-hedgefund/blob/main/main.py): entrypoint · Local/production entrypoint · `main.py`
- [Server](https://github.com/agentuity/agent-hedgefund/blob/main/server.py): serve layer · HTTP/server boundary for the agent · `server.py`

### Workflow orchestration

LangGraph composition and state routing

- [Agent root](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/agent.py): composition root · Wires the hedge fund graph together · `agents/hedge_fund/agent.py`
- [Workflow state](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/models/workflow.py): state contract · Shared graph state passed between nodes · `agents/hedge_fund/models/workflow.py`
- [Parsing](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/parsing.py): workflow node · Extracts intent and user context · `agents/hedge_fund/nodes/parsing.py`
- [Routing](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/routing.py): workflow node · Chooses the downstream path · `agents/hedge_fund/nodes/routing.py`
- [Search](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/search.py): workflow node · Resolves user language to a tradable asset · `agents/hedge_fund/nodes/search.py`
- [Analysis](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/analysis.py): workflow node · Runs market and sentiment analysis stages · `agents/hedge_fund/nodes/analysis.py`
- [Risk](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/risk_management.py): workflow node · Applies risk constraints and checks · `agents/hedge_fund/nodes/risk_management.py`
- [Portfolio](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/portfolio_manager.py): workflow node · Converts analysis into a portfolio action · `agents/hedge_fund/nodes/portfolio_manager.py`
- [Response](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/nodes/llm_response.py): workflow node · Formats the final recommendation for the user · `agents/hedge_fund/nodes/llm_response.py`

### Domain services

Business logic and decision helpers

- [Controller](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/controller.py): orchestrator service · Coordinates the end-to-end agent flow · `agents/hedge_fund/services/controller.py`
- [Asset search](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/asset_search_service.py): domain service · Maps requests to symbols and instruments · `agents/hedge_fund/services/asset_search_service.py`
- [Technical](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/technical_analyst.py): domain service · Coordinates technical market analysis · `agents/hedge_fund/services/technical_analyst.py`
- [Sentiment](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/market_sentiment_analyst.py): domain service · Coordinates news, macro, and fear-greed context · `agents/hedge_fund/services/market_sentiment_analyst.py`
- [Risk manager](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/risk_manager_service.py): domain service · Evaluates constraints and recommendation risk · `agents/hedge_fund/services/risk_manager_service.py`
- [Decision engine](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/trade_decision_service.py): domain service · Produces buy/sell/hold and sizing guidance · `agents/hedge_fund/services/trade_decision_service.py`
- [Formatter](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/services/response_formatter_service.py): domain service · Builds the final user-facing answer · `agents/hedge_fund/services/response_formatter_service.py`

### Analysis tools

Market, sentiment, and technical analysis utilities

- [Action parser](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/action_parser.py): parser utility · Normalizes intent from natural language · `agents/hedge_fund/tools/action_parser.py`
- [Asset lookup](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/asset_search.py): lookup utility · Low-level tradable asset search · `agents/hedge_fund/tools/asset_search.py`
- [Tech manager](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/technical/manager.py): analysis coordinator · Runs the technical analysis pipeline · `agents/hedge_fund/tools/technical/manager.py`
- [Market data](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/technical/data_fetcher.py): data acquisition · Pulls live price and market data · `agents/hedge_fund/tools/technical/data_fetcher.py`
- [Indicators](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/technical/indicators.py): indicator engine · Computes RSI, MACD, EMA and related signals · `agents/hedge_fund/tools/technical/indicators.py`
- [Signal interp](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/technical/signal_interpreter.py): signal translator · Converts indicator values into directional signals · `agents/hedge_fund/tools/technical/signal_interpreter.py`
- [Sentiment manager](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/sentiment/manager.py): analysis coordinator · Runs sentiment and macro sub-analyses · `agents/hedge_fund/tools/sentiment/manager.py`
- [News](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/sentiment/news_analyzer.py): news analysis · Extracts sentiment from news sources · `agents/hedge_fund/tools/sentiment/news_analyzer.py`
- [Macro](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/sentiment/economic_analyzer.py): macro analysis · Uses economic indicators and FRED-backed context · `agents/hedge_fund/tools/sentiment/economic_analyzer.py`
- [Fear greed](https://github.com/agentuity/agent-hedgefund/blob/main/agents/hedge_fund/tools/sentiment/fear_greed_analyzer.py): sentiment signal · Reads market fear/greed sentiment · `agents/hedge_fund/tools/sentiment/fear_greed_analyzer.py`

## Connections

- Agentuity → Main: deploys · Agentuity launches the application entrypoint
- Agentuity → Server: serves · Hosted runtime exposes the agent through the server boundary
- Main → Agent root: starts · Entrypoint initializes the hedge fund agent
- Server → Agent root: routes to · Server hands requests to the graph composition root
- Agent root → Workflow state: uses state · Graph operates over shared workflow state
- Agent root → Parsing: wires · Composition root connects the workflow stages
- Parsing → Action parser: parses with · User request is normalized into intent and context
- Parsing → Routing: outputs · Parsed state feeds routing decisions
- Routing → Search: may branch to · Requests needing symbol resolution go to search
- Routing → Analysis: may branch to · Resolved trades proceed to analysis
- Search → Asset search: uses · Search node delegates symbol resolution
- Asset search → Asset lookup: looks up · Service uses the lower-level asset lookup utility
- Analysis → Technical: runs · Technical analysis is coordinated here
- Analysis → Sentiment: runs · Sentiment and macro context are coordinated here
- Technical → Tech manager: coordinates · Service delegates to the technical toolchain
- Tech manager → Market data: fetches · Market data is retrieved first
- Tech manager → Indicators: computes · Indicator values are derived from data
- Tech manager → Signal interp: interprets · Signals are translated into actionable direction
- Sentiment → Sentiment manager: coordinates · Service delegates to sentiment tools
- Sentiment manager → News: analyzes · News sentiment is derived from headlines and articles
- Sentiment manager → Macro: analyzes · Macro context is derived from economic indicators
- Sentiment manager → Fear greed: analyzes · Fear/greed conditions are incorporated
- Analysis → Risk: feeds · Analysis results flow into risk checks
- Risk → Risk manager: checks with · Risk service evaluates constraints and exposure
- Risk → Portfolio: passes · Validated state continues to portfolio decisions
- Portfolio → Decision engine: decides with · Trade decision logic produces the recommendation
- Decision engine → Formatter: hands off to · Decision output is formatted for presentation
- Portfolio → Response: updates · Portfolio decision state feeds the response step
- Response → Formatter: formats with · Final response is rendered from structured decision data
- Formatter → Controller: returns via · Controller can assemble the final answer from services
