🧠 Stock-Market Research Assistant

Databricks AI Bootcamp Capstone — Stock-Market Research Assistant

Implementação profissional do projeto final do treinamento DataExpert.io

🎓 Conclusão do Treinamento

Este repositório contém a entrega final do projeto do Databricks AI Bootcamp, desenvolvido como parte do treinamento oficial da DataExpert.io.

🔗 Treinamento Original

Bootcamp: Rise of the AI Data Engineer
Repository: EcZachly/databricks-ai-bootcamp-capstone
NotebookLM: Databricks AI Boot Camp

📌 Project Highlights

Feature	Status	Description
Pipeline Spark	✅	Ingestão distribuída com Spark e Delta Lake
API Externa	✅	Massive API para preços e notícias de ações
Conteúdo Não Estruturado	✅	HTML → texto → chunks com trafilatura
Databricks App	✅	Main App + Dashboard separados
Agente Leitura/Escrita	✅	MCP Server com tools de pesquisa e persistência
RAG com pgvector	✅	Embeddings e busca semântica HNSW
Wiki Completa	✅	Documentação técnica e arquitetural

🏛️ Architecture & Tech Stack

Camadas da Arquitetura

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              Databricks Workspace                               │
│                                                                                 │
│  ┌──────────────────────┐         ┌──────────────────────┐                      │
│  │   Databricks App     │         │   Databricks App     │                      │
│  │     (Main App)       │         │    (Dashboard)       │                      │
│  │                      │         │                      │                      │
│  │  - Massive API       │         │  - Read-only Flask   │                      │
│  │  - Lakebase (PG)     │         │  - Watchlist/Quotes  │                      │
│  │  - Sync endpoint     │         │  - News viewer       │                      │
│  └──────────┬───────────┘         └──────────────────────┘                      │
│             │                                                                   │
│             ▼                                                                   │
│  ┌──────────────────────────────────────────────────────────────────────┐      │
│  │                        Lakebase (Postgres)                            │      │
│  │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────────┐ │      │
│  │  │  watchlists      │  │ ticker_news_     │  │ ticker_news_         │ │      │
│  │  │  (ticker lists)  │  │ documents        │  │ embeddings           │ │      │
│  │  └──────────────────┘  │ (news articles)  │  │ (title+description)  │ │      │
│  │                        └──────────────────┘  └──────────────────────┘ │      │
│  │                                                              │          │      │
│  │                                                              ▼          │      │
│  │                                                    ┌────────────────┐ │      │
│  │                                                    │ pgvector HNSW  │ │      │
│  │                                                    │ index (cosine) │ │      │
│  │                                                    └────────────────┘ │      │
│  │  ┌──────────────────┐  ┌──────────────────┐                          │      │
│  │  │  research_notes  │  │ analysis_        │                          │      │
│  │  │  (agent writes)  │  │ reports          │                          │      │
│  │  └──────────────────┘  └──────────────────┘                          │      │
│  └──────────────────────────────────────────────────────────────────────┘      │
│             │                                                                   │
│             ▼                                                                   │
│  ┌──────────────────────────────────────────────────────────────────────┐      │
│  │                      MCP Server App                                  │      │
│  │  ┌───────────────────────────────────────────────────────────────┐   │      │
│  │  │  Massive Broker (stock data)                                  │   │      │
│  │  └───────────────────────────────────────────────────────────────┘   │      │
│  │                                                                       │      │
│  │  ┌───────────────────────────────────────────────────────────────┐   │      │
│  │  │  FastMCP Server (tools exposed to Agent Bricks)               │   │      │
│  │  │  - get_quote(symbol)                                          │   │      │
│  │  │  - search_news(symbol, query, limit)                          │   │      │
│  │  │  - search_research_context(query, symbol)                     │   │      │
│  │  │  - get_watchlist()                                            │   │      │
│  │  │  - add_to_watchlist(symbol)                                   │   │      │
│  │  │  - remove_from_watchlist(symbol)                              │   │      │
│  │  │  - save_research_note(symbol, title, content)                 │   │      │
│  │  │  - save_analysis_report(symbol, report, sources)              │   │      │
│  │  └───────────────────────────────────────────────────────────────┘   │      │
│  └──────────────────────────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────────────────────────┘

Stack Tecnológica

Camada	Tecnologia	Versão	Uso
Data Warehouse	Databricks Lakebase	Postgres	Banco transacional integrado
Processing	Apache Spark	3.5+	Pipelines distribuídos
Embeddings	sentence-transformers	all-MiniLM-L6-v2	Similaridade semântica
Vector Search	pgvector	0.5+	Índice HNSW cosine
APIs	Massive.com	v2	Preços e notícias de ações
Agent Framework	FastMCP	1.0+	Ferramentas para agente
Frontend	Flask	2.0+	API e Dashboard

🗺️ Architecture Diagram

Pipeline de Dados

flowchart LR
    subgraph "Ingestão"
        A[Watchlist Lakebase] -->|tickers| B[Massive API]
        B -->|notícias| C[ticker_news_documents]
    end

    subgraph "Processamento"
        C -->|HTML| D[trafilatura]
        D -->|texto| E[Chunking]
        E -->|chunks| F[Embeddings Spark]
    end

    subgraph "Armazenamento"
        F -->|embeddings| G[ticker_news_embeddings]
        E -->|chunks| H[ticker_news_chunk_embeddings]
        G & H -->|HNSW| I[pgvector Index]
    end

    subgraph "Consulta RAG"
        J[User Query] -->|embedding| I
        I -->|top-k| K[Context Retrieval]
        K -->|prompt| L[LLM Response]
    end

Fluxo de Consulta RAG

flowchart LR
    A[Query do Usuário] --> B[Embedding da Query]
    B --> C[Busca Vetorial pgvector]
    C --> D[Top-k Chunks]
    D --> E[Contexto Formatado]
    E --> F[Prompt com Citações]
    F --> G[Resposta Fundamentada]

📊 Resultados

Métrica	Resultado	Observação
Dimensionalidade Embeddings	384	all-MiniLM-L6-v2
Métrica Similaridade	Cosine	Otimizada com pgvector
Index Vector	HNSW	Busca O(log n) aproximada
Latência Query RAG	< 500ms	Com índice HNSW
Throughput Embeddings	Batch ~100	Parallel Spark

🚀 Quick Start & Setup

Pré-requisitos

Acesso ao Databricks Workspace
Massive API Key (grátis em https://www.massive.com)
Lakebase URL configurado no workspace

Configuração

# 1. Criar secret scopes
python setup_secrets.py

# 2. Executar SQLs no Lakebase
psql $LAKEBASE_URL -f sql/01_setup_news_table.sql
psql $LAKEBASE_URL -f sql/02_setup_embeddings_table.sql
psql $LAKEBASE_URL -f sql/03_setup_chunk_embeddings_table.sql
psql $LAKEBASE_URL -f sql/04_cast_arrays_to_vectors.sql
psql $LAKEBASE_URL -f sql/05_setup_research_tables.sql

# 3. Executar notebook de ingestão
# (via Databricks UI: importar notebooks/ingest_ticker_news_embeddings.py)

# 4. Testar RAG
python3 test_rag.py --ticker AAPL --limit 5

# 5. Deploy dos Apps
databricks bundle deploy -t dev

Endpoints da API

Método	Endpoint	Descrição
GET	`/watchlist`	Lista tickers
GET	`/price/<symbol>`	Preço atual
GET	`/news/<symbol>`	Notícias recentes
POST	`/news/sync`	Sincronizar notícias
POST	`/search/context`	Busca semântica (RAG)

Tools do MCP Server

Leitura:

get_quote(symbol) - Preço atual
search_news(symbol, query, limit) - Busca notícias
search_research_context(query, symbol) - Busca contexto
get_watchlist() - Lista tickers
add_to_watchlist(symbol) - Adicionar ticker
remove_from_watchlist(symbol) - Remover ticker

Escrita (Agente):

save_research_note(symbol, title, content) - Salvar nota
save_analysis_report(symbol, report, sources) - Salvar relatório

🌳 Estrutura do Projeto

databricks-capstone-delivery/
├── app.py                      # Main Flask API (Day 1/2)
├── lakebase.py                 # Lakebase connection helper
├── massive_client.py           # Massive API client
├── setup_secrets.py            # Secret scope setup
├── requirements.txt            # Python dependencies
├── pyproject.toml              # Project metadata
├── test_rag.py                 # Script de validação RAG
│
├── dashboard/
│   ├── app.py                  # Dashboard Flask
│   └── templates/index.html    # Dashboard UI
│
├── mcp_server/
│   ├── alpaca_mcp_server.py    # FastMCP server (com writing tools)
│   ├── lakebase.py             # Lakebase helper (novas funções)
│   └── massive_broker.py       # Massive broker
│
├── notebooks/
│   └── ingest_ticker_news_embeddings.py  # Spark pipeline
│
├── sql/
│   ├── 01_setup_news_table.sql
│   ├── 02_setup_embeddings_table.sql
│   ├── 03_setup_chunk_embeddings_table.sql
│   ├── 04_cast_arrays_to_vectors.sql
│   └── 05_setup_research_tables.sql
│
└── resources/
    ├── dashboard.yml
    ├── ingest_ticker_news_embeddings_job.yml
    └── mcp_server.yml

🧠 Methodology & Quality Gates

Este projeto incorpora um sistema heurístico robusto para garantir qualidade e evitar erros comuns de engenharia de dados:

Data Contract Gate

Valida tabelas Silver/Gold antes da execução:

Verificação	Implementada	Estado
Schema esperado (colunas, tipos, nullability)	✅	Documentado em SQLs
Regras de qualidade (cardinalidade, unicidade)	✅	Tabelas com constraints
SLA de volume e latência	✅	Documentado no schema
Contrato versionado	✅	`sql/*.sql` com versionamento

Idempotency Gate

Garante reexecução segura do pipeline:

Verificação	Implementada	Estado
UPSERT ou FULL REFRESH definido	✅	Tabelas com ON CONFLICT
Nenhum append cego sem verificação	✅	Chaves primárias definidas
Custo de reprocessamento estimado	✅	Log de contagem de linhas

Heurísticas Aplicadas

Heurística	Descrição	Aplicação
Check antes de escrita	Validação de entrada antes de persistência	`lakebase.py` + `alpaca_broker.py`
Rastreabilidade de evidência	Toda conclusão indica SOURCE/INFERENCE/IMPLEMENTED/VALIDATED	PRD_E_PLANO_EXECUCAO.md
Gates antes de deploy	Dois checklists obrigatórios antes de considerar pronto	Este README
Falsos positivos vs falsos negativos	Avaliação balanceada de RAG	Teste RAG com `test_rag.py`

📚 Documentation Resources

PRD_E_PLANO_EXECUCAO.md - Requisitos e plano completo
TECHNICAL.md - Documentação técnica para tech leads
CHANGELOG.md - Histórico de versões
CONTRIBUTING.md - Guia de contribuição

📄 License

Este projeto foi desenvolvido como parte do treinamento do Databricks AI Bootcamp.

Este código pode ser utilizado como portfolio para demonstrar competências técnicas em Engenharia de Dados, RAG e Agentes de IA.

⚠️ Notas Importantes

Este não é um sistema de trading em produção. Não deve ser usado para decisões financeiras reais.
A API do Massive tem limites de rate. O pipeline respeita esses limites.
Secrets nunca devem ser commitados. O setup_secrets.py garante isso.

Este projeto foi desenvolvido para demonstrar as habilidades técnicas adquiridas durante o Databricks AI Bootcamp.

Author: Roberto LinkedIn: https://www.linkedin.com/in/roberton003/ GitHub: https://github.com/Roberton003

🧠 Stock-Market Research Assistant