Add Finance Agent Example

FinanceAgent/README.md

@@ -0,0 +1,145 @@
+# Finance Agent
+
+## 1. Overview
+
+The architecture of this Finance Agent example is shown in the figure below. The agent has 3 main functions:
+
+1. Summarize long financial documents and provide key points.
+2. Answer questions over financial documents, such as SEC filings.
+3. Conduct research of a public company and provide an investment report of the company.
+
+![Finance Agent Architecture](assets/finance_agent_arch.png)
+
+The `dataprep` microservice can ingest financial documents in two formats:
+
+1. PDF documents stored locally, such as SEC filings saved in local directory.
+2. URLs, such as earnings call transcripts ([example](https://www.fool.com/earnings/call-transcripts/2025/03/06/costco-wholesale-cost-q2-2025-earnings-call-transc/)) and online SEC filings ([example](https://investors.3m.com/financials/sec-filings/content/0000066740-25-000006/0000066740-25-000006.pdf)).
+
+Please note:
+
+1. Each financial document should be about one company.
+2. URLs ending in `.htm` are not supported.
+
+## 2. Getting started
+
+### 2.1 Download repos
+
+```bash
+mkdir /path/to/your/workspace/
+export WORKDIR=/path/to/your/workspace/
+genaicomps
+genaiexamples
+```
+
+### 2.2 Set up env vars
+
+```bash
+export HF_CACHE_DIR=/path/to/your/model/cache/
+export HF_TOKEN=<you-hf-token>
+
+```
+
+### 2.3 Build docker images
+
+Build docker images for dataprep, agent, agent-ui.
+
+```bash
+cd GenAIExamples/FinanceAgent/docker_image_build
+docker compose -f build.yaml build --no-cache
+```
+
+If deploy on Gaudi, also need to build vllm image.
+
+```bash
+cd $WORKDIR
+git clone https://github.com/HabanaAI/vllm-fork.git
+# get the latest release tag of vllm gaudi
+cd vllm-fork
+VLLM_VER=$(git describe --tags "$(git rev-list --tags --max-count=1)")
+echo "Check out vLLM tag ${VLLM_VER}"
+git checkout ${VLLM_VER}
+docker build --no-cache -f Dockerfile.hpu -t opea/vllm-gaudi:latest --shm-size=128g . --build-arg https_proxy=$https_proxy --build-arg http_proxy=$http_proxy
+```
+
+## 3. Deploy with docker compose
+
+### 3.1 Launch vllm endpoint
+
+Below is the command to launch a vllm endpoint on Gaudi that serves `meta-llama/Llama-3.3-70B-Instruct` model on 4 Gaudi cards.
+
+```bash
+cd $WORKDIR/GenAIExamples/FinanceAgent/docker_compose/intel/hpu/gaudi
+bash launch_vllm.sh
+```
+
+### 3.2 Prepare knowledge base
+
+The commands below will upload some example files into the knowledge base. You can also upload files through UI.
+
+First, launch the redis databases and the dataprep microservice.
+
+```bash
+# inside $WORKDIR/GenAIExamples/FinanceAgent/docker_compose/intel/hpu/gaudi/
+bash launch_dataprep.sh
+```
+
+Validate datat ingest data and retrieval from database:
+
+```bash
+python $WORKPATH/tests/test_redis_finance.py --port 6007 --test_option ingest
+python $WORKPATH/tests/test_redis_finance.py --port 6007 --test_option get
+```
+
+### 3.3 Launch the multi-agent system
+
+```bash
+# inside $WORKDIR/GenAIExamples/FinanceAgent/docker_compose/intel/hpu/gaudi/
+bash launch_agents.sh
+```
+
+### 3.4 Validate agents
+
+FinQA Agent:
+
+```bash
+export agent_port="9095"
+prompt="What is Gap's revenue in 2024?"
+python3 $WORKDIR/GenAIExamples/FinanceAgent/tests/test.py --prompt "$prompt" --agent_role "worker" --ext_port $agent_port
+```
+
+Research Agent:
+
+```bash
+export agent_port="9096"
+prompt="generate NVDA financial research report"
+python3 $WORKDIR/GenAIExamples/FinanceAgent/tests/test.py --prompt "$prompt" --agent_role "worker" --ext_port $agent_port --tool_choice "get_current_date" --tool_choice "get_share_performance"
+```
+
+Supervisor ReAct Agent:
+
+```bash
+export agent_port="9090"
+python3 $WORKDIR/GenAIExamples/FinanceAgent/tests/test.py --agent_role "supervisor" --ext_port $agent_port --stream
+```
+
+Supervisor ReAct Agent Multi turn:
+
+```bash
+python3 $WORKDIR/GenAIExamples/FinanceAgent/tests/test.py --agent_role "supervisor" --ext_port $agent_port --multi-turn --stream
+
+```
+
+## How to interact with the agent system with UI
+
+The UI microservice is launched in the previous step with the other microservices.
+To see the UI, open a web browser to `http://${ip_address}:5175` to access the UI. Note the `ip_address` here is the host IP of the UI microservice.
+
+1. `create Admin Account` with a random value
+
+2. use an opea agent endpoint, for example, the `Research Agent` endpoint `http://$ip_address:9096/v1`, which is a openai compatible api
+
+![opea-agent-setting](assets/opea-agent-setting.png)
+
+3. test opea agent with ui
+
+![opea-agent-test](assets/opea-agent-test.png)

FinanceAgent/docker_compose/intel/hpu/gaudi/compose.yaml

@@ -0,0 +1,133 @@
+# Copyright (C) 2024 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+services:
+  worker-finqa-agent:
+    image: opea/agent:latest
+    container_name: finqa-agent-endpoint
+    volumes:
+      - ${TOOLSET_PATH}:/home/user/tools/
+      - ${PROMPT_PATH}:/home/user/prompts/
+    ports:
+      - "9095:9095"
+    ipc: host
+    environment:
+      ip_address: ${ip_address}
+      strategy: react_llama
+      with_memory: false
+      recursion_limit: ${recursion_limit_worker}
+      llm_engine: vllm
+      HUGGINGFACEHUB_API_TOKEN: ${HUGGINGFACEHUB_API_TOKEN}
+      llm_endpoint_url: ${LLM_ENDPOINT_URL}
+      model: ${LLM_MODEL_ID}
+      temperature: ${TEMPERATURE}
+      max_new_tokens: ${MAX_TOKENS}
+      stream: false
+      tools: /home/user/tools/finqa_agent_tools.yaml
+      custom_prompt: /home/user/prompts/finqa_prompt.py
+      require_human_feedback: false
+      no_proxy: ${no_proxy}
+      http_proxy: ${http_proxy}
+      https_proxy: ${https_proxy}
+      REDIS_URL_VECTOR: $REDIS_URL_VECTOR
+      REDIS_URL_KV: $REDIS_URL_KV
+      TEI_EMBEDDING_ENDPOINT: $TEI_EMBEDDING_ENDPOINT
+      port: 9095
+
+  worker-research-agent:
+    image: opea/agent:latest
+    container_name: research-agent-endpoint
+    volumes:
+      - ${TOOLSET_PATH}:/home/user/tools/
+      - ${PROMPT_PATH}:/home/user/prompts/
+    ports:
+      - "9096:9096"
+    ipc: host
+    environment:
+      ip_address: ${ip_address}
+      strategy: react_llama
+      with_memory: false
+      recursion_limit: ${recursion_limit_worker}
+      llm_engine: vllm
+      HUGGINGFACEHUB_API_TOKEN: ${HUGGINGFACEHUB_API_TOKEN}
+      llm_endpoint_url: ${LLM_ENDPOINT_URL}
+      model: ${LLM_MODEL_ID}
+      stream: false
+      tools: /home/user/tools/research_agent_tools.yaml
+      custom_prompt: /home/user/prompts/research_prompt.py
+      require_human_feedback: false
+      no_proxy: ${no_proxy}
+      http_proxy: ${http_proxy}
+      https_proxy: ${https_proxy}
+      FINNHUB_API_KEY: ${FINNHUB_API_KEY}
+      FINANCIAL_DATASETS_API_KEY: ${FINANCIAL_DATASETS_API_KEY}
+      port: 9096
+
+  supervisor-react-agent:
+    image: opea/agent:latest
+    container_name: supervisor-agent-endpoint
+    depends_on:
+      - worker-finqa-agent
+      # - worker-research-agent
+    volumes:
+      - ${TOOLSET_PATH}:/home/user/tools/
+      - ${PROMPT_PATH}:/home/user/prompts/
+    ports:
+      - "9090:9090"
+    ipc: host
+    environment:
+      ip_address: ${ip_address}
+      strategy: react_llama
+      with_memory: true
+      recursion_limit: ${recursion_limit_supervisor}
+      llm_engine: vllm
+      HUGGINGFACEHUB_API_TOKEN: ${HUGGINGFACEHUB_API_TOKEN}
+      llm_endpoint_url: ${LLM_ENDPOINT_URL}
+      model: ${LLM_MODEL_ID}
+      temperature: ${TEMPERATURE}
+      max_new_tokens: ${MAX_TOKENS}
+      stream: true
+      tools: /home/user/tools/supervisor_agent_tools.yaml
+      custom_prompt: /home/user/prompts/supervisor_prompt.py
+      require_human_feedback: false
+      no_proxy: ${no_proxy}
+      http_proxy: ${http_proxy}
+      https_proxy: ${https_proxy}
+      WORKER_FINQA_AGENT_URL: $WORKER_FINQA_AGENT_URL
+      WORKER_RESEARCH_AGENT_URL: $WORKER_RESEARCH_AGENT_URL
+      DOCSUM_ENDPOINT: $DOCSUM_ENDPOINT
+      REDIS_URL_VECTOR: $REDIS_URL_VECTOR
+      REDIS_URL_KV: $REDIS_URL_KV
+      TEI_EMBEDDING_ENDPOINT: $TEI_EMBEDDING_ENDPOINT
+      port: 9090
+
+  docsum-vllm-gaudi:
+    image: opea/llm-docsum:latest
+    container_name: docsum-vllm-gaudi
+    ports:
+      - ${DOCSUM_PORT:-9000}:9000
+    ipc: host
+    environment:
+      no_proxy: ${no_proxy}
+      http_proxy: ${http_proxy}
+      https_proxy: ${https_proxy}
+      LLM_ENDPOINT: ${LLM_ENDPOINT}
+      LLM_MODEL_ID: ${LLM_MODEL_ID}
+      HF_TOKEN: ${HF_TOKEN}
+      LOGFLAG: ${LOGFLAG:-False}
+      MAX_INPUT_TOKENS: ${MAX_INPUT_TOKENS}
+      MAX_TOTAL_TOKENS: ${MAX_TOTAL_TOKENS}
+      DocSum_COMPONENT_NAME: ${DocSum_COMPONENT_NAME:-OpeaDocSumvLLM}
+    restart: unless-stopped
+
+  agent-ui:
+    image: opea/agent-ui:latest
+    container_name: agent-ui
+    environment:
+      host_ip: ${host_ip}
+      no_proxy: ${no_proxy}
+      http_proxy: ${http_proxy}
+      https_proxy: ${https_proxy}
+    ports:
+      - "5175:8080"
+    ipc: host

FinanceAgent/docker_compose/intel/hpu/gaudi/dataprep_compose.yaml

@@ -0,0 +1,82 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+services:
+  tei-embedding-serving:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.5
+    container_name: tei-embedding-serving
+    entrypoint: /bin/sh -c "apt-get update && apt-get install -y curl && text-embeddings-router --json-output --model-id ${EMBEDDING_MODEL_ID} --auto-truncate"
+    ports:
+      - "${TEI_EMBEDDER_PORT:-10221}:80"
+    volumes:
+      - "./data:/data"
+    shm_size: 1g
+    environment:
+      no_proxy: ${no_proxy}
+      http_proxy: ${http_proxy}
+      https_proxy: ${https_proxy}
+      host_ip: ${host_ip}
+      HF_TOKEN: ${HF_TOKEN}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://${host_ip}:${TEI_EMBEDDER_PORT}/health"]
+      interval: 10s
+      timeout: 6s
+      retries: 48
+
+  redis-vector-db:
+    image: redis/redis-stack:7.2.0-v9
+    container_name: redis-vector-db
+    ports:
+      - "${REDIS_PORT1:-6379}:6379"
+      - "${REDIS_PORT2:-8001}:8001"
+    environment:
+      - no_proxy=${no_proxy}
+      - http_proxy=${http_proxy}
+      - https_proxy=${https_proxy}
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+
+  redis-kv-store:
+    image: redis/redis-stack:7.2.0-v9
+    container_name: redis-kv-store
+    ports:
+      - "${REDIS_PORT3:-6380}:6379"
+      - "${REDIS_PORT4:-8002}:8001"
+    environment:
+      - no_proxy=${no_proxy}
+      - http_proxy=${http_proxy}
+      - https_proxy=${https_proxy}
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+
+  dataprep-redis-finance:
+    image: ${REGISTRY:-opea}/dataprep:${TAG:-latest}
+    container_name: dataprep-redis-server-finance
+    depends_on:
+      redis-vector-db:
+        condition: service_healthy
+      redis-kv-store:
+        condition: service_healthy
+      tei-embedding-serving:
+        condition: service_healthy
+    ports:
+      - "${DATAPREP_PORT:-6007}:5000"
+    environment:
+      no_proxy: ${no_proxy}
+      http_proxy: ${http_proxy}
+      https_proxy: ${https_proxy}
+      DATAPREP_COMPONENT_NAME: ${DATAPREP_COMPONENT_NAME}
+      REDIS_URL_VECTOR: ${REDIS_URL_VECTOR}
+      REDIS_URL_KV: ${REDIS_URL_KV}
+      TEI_EMBEDDING_ENDPOINT: ${TEI_EMBEDDING_ENDPOINT}
+      LLM_ENDPOINT: ${LLM_ENDPOINT}
+      LLM_MODEL: ${LLM_MODEL}
+      HUGGINGFACEHUB_API_TOKEN: ${HF_TOKEN}
+      HF_TOKEN: ${HF_TOKEN}
+      LOGFLAG: true

FinanceAgent/docker_compose/intel/hpu/gaudi/launch_agents.sh

@@ -0,0 +1,36 @@
+
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+export ip_address=$(hostname -I | awk '{print $1}')
+export HUGGINGFACEHUB_API_TOKEN=${HF_TOKEN}
+export TOOLSET_PATH=$WORKDIR/GenAIExamples/FinanceAgent/tools/
+echo "TOOLSET_PATH=${TOOLSET_PATH}"
+export PROMPT_PATH=$WORKDIR/GenAIExamples/FinanceAgent/prompts/
+echo "PROMPT_PATH=${PROMPT_PATH}"
+export recursion_limit_worker=12
+export recursion_limit_supervisor=10
+
+vllm_port=8086
+export LLM_MODEL_ID="meta-llama/Llama-3.3-70B-Instruct"
+export LLM_ENDPOINT_URL="http://${ip_address}:${vllm_port}"
+export TEMPERATURE=0.5
+export MAX_TOKENS=4096
+
+export WORKER_FINQA_AGENT_URL="http://${ip_address}:9095/v1/chat/completions"
+export WORKER_RESEARCH_AGENT_URL="http://${ip_address}:9096/v1/chat/completions"
+
+export EMBEDDING_MODEL_ID="BAAI/bge-base-en-v1.5"
+export TEI_EMBEDDING_ENDPOINT="http://${ip_address}:10221"
+export REDIS_URL_VECTOR="redis://${ip_address}:6379"
+export REDIS_URL_KV="redis://${ip_address}:6380"
+
+export MAX_INPUT_TOKENS=2048
+export MAX_TOTAL_TOKENS=4096
+export DocSum_COMPONENT_NAME="OpeaDocSumvLLM"
+export DOCSUM_ENDPOINT="http://${ip_address}:9000/v1/docsum"
+
+export FINNHUB_API_KEY=${FINNHUB_API_KEY}
+export FINANCIAL_DATASETS_API_KEY=${FINANCIAL_DATASETS_API_KEY}
+
+docker compose -f compose.yaml up -d