FinAI Research Workflow

Fluxo de Trabalho de Pesquisa em Artigos e Relatórios · FinAI Research Workflow

Uma frase sobre o tema de pesquisa → receba um rascunho LaTeX verificável. Descreva seu tópico de pesquisa → receba um rascunho LaTeX verificável.

---

Início Rápido (30 segundos para começar)

# ── 推荐方式：PyPI wheel 安装（首次约 60s）────────────────────────────
# Debian/Ubuntu：先创建虚拟环境，避免与系统 Python 冲突
python3 -m venv .venv && source .venv/bin/activate
pip install "finai-research-workflow[extras]"

# 配置 LLM（DeepSeek 直连，免费）
export DEEPSEEK_API_KEY=sk-xxxx

# 启动流水线（wheel 安装后的写作入口；加 --use-hitl 启用阶段门控）
finai-pipeline --topic "Carbon trading and green innovation" --use-hitl
# 或
python -m finai.pipeline --topic "碳排放权交易与企业绿色创新" --use-hitl

# ── 源码安装（推荐贡献者 / 想改代码的用户）────────────────────────────
git clone https://github.com/csmar432/finai-research.git && cd finai-research
pip install -e ".[extras]"
cp .env.example .env.local   # 编辑 .env.local：DEEPSEEK_API_KEY=sk-...
# 新用户：先澄清（不自动开跑）→ 再写作；或澄清时加 --continue
python scripts/start_research.py --topic "Carbon trading and green innovation"
python scripts/agent_pipeline.py --topic "Carbon trading and green innovation" --use-hitl

# ── Debian/Ubuntu apt 系统 Python ─────────────────────────────────────
# apt 的 Python 被系统管理，直接 pip install 会触发 PEP 668 冲突。
# 解法：使用虚拟环境（见上方），或加 --break-system-packages
pip install --break-system-packages "finai-research-workflow[extras]"

Aviso importante: quando DEEPSEEK_API_KEY estiver ausente, finai-pipeline sairá por padrão com o código de saída 4 (modo estrito) e exibirá instruções claras. Você pode usar finai-doctor para diagnosticar a origem da configuração.

PyPI: finai-research-workflow · 0.3.1 · MIT · A instalação padrão do pip install finai-research-workflow não inclui fastapi/streamlit (para evitar conflitos com PyJWT/apt) · Pacote Web: pip install 'finai-research-workflow[web]' DOI: 10.5281/zenodo.21262689

Demonstração Rápida

Este passo a passo guiado da interface mostra os hosts de agente suportados, o checkpoint do resumo de pesquisa, as trilhas separadas de escrita e empírica, o roteamento de dados com falha segura e o pacote de entrega verificável. Ele não é apresentado intencionalmente como uma execução de pesquisa ao vivo e não contém coeficientes simulados, citações ou alegações estatísticas. Regere-o deterministicamente com python scripts/demo/gen_quick_demo.py; consulte .github/demo/README.md para o contrato visual.

Uma entrada → pipeline de 8 estágios: geração de ideias → revisão de literatura → verificação de novidade → desenho empírico → aquisição de dados → análise → redação do artigo → revisão adversarial. Cada estágio requer confirmação do pesquisador.

---

3 Capacidades Principais

43 fontes de dados MCP	Finanças A-share / Ações dos EUA / Macroeconomia (FRED/IMF/Banco Mundial) / Artigos acadêmicos (OpenAlex/ArXiv), 28 sem necessidade de API Key
58 módulos econométricos	Cobre DID padrão / DID escalonado (CS/SunAb/Borusyak) / IV / RDD / Controle sintético / GMM em painel, testes de robustez nível JF/JFE
30 modelos de periódicos	JF / JFE / RFS / 经济研究 / 金融研究 / 管理世界, em quatro idiomas: chinês, inglês, japonês e alemão

⚠️ Estratégias de identificação causal, resultados estatísticos e citações gerados por IA devem ser verificados de forma independente pelo pesquisador antes da submissão. ⚠️ Dados simulados / sintéticos são desabilitados por padrão; só podem ser ativados com autorização explícita do usuário, e a saída deve conter o identificador ⚠️ MOCK DATA.

---

Documentação completa: 使用指南.md · CLAUDE.md · execute python scripts/setup_wizard.py --guided

---

Por que o FinAI Research Workflow?

• Feito para economistas, não para demonstrações genéricas de IA — cada padrão é calibrado para o padrão do Journal of Finance / 经济研究 (DID com efeitos de tratamento heterogêneos, erros-padrão robustos por cluster no nível da firma, 19 verificações de robustez, gráficos de tendência paralela).
• 43 diretórios de servidores MCP — cobre finanças A-share, ações dos EUA, macro global (FRED/Banco Mundial/FMI/OCDE/BEA) e mais de 400 milhões de artigos acadêmicos (OpenAlex). O registro contém 28 diretórios sem chave, 12 com API key, 0 stub e 3 de risco legal opcionais; a classificação é mantida por scripts/count_assets.py.
• 58 módulos de métodos econométricos, não apenas OLS — DID padrão, estudo de evento, decomposição de Bacon, diagnósticos de tratamento heterogêneo, controle sintético, variáveis instrumentais (linearmodels opcional), GMM em painel, RDD, mediação e muito mais. Métodos que exigem um backend externo falham visivelmente quando ele não está disponível; consulte CLAUDE.md para notas de dependência.
• 30 modelos de periódicos, em inglês/chinês/japonês/alemão — JF, JFE, RFS, JAE, Econometrica, 经济研究, 金融研究, 管理世界, 会计研究, 中国工业经济.
• 18 habilidades especializadas de IA (Claude Code / Cursor / GitHub Copilot) — descoberta de ideias, revisão de literatura, verificação de novidade, desenho experimental, aquisição de dados, redação de artigos, geração de figuras, compilação LaTeX, ciclos de revisão.
• Humano no circuito, nunca fabricação autônoma — cada estágio exige aprovação explícita em checkpoint; as fontes de dados são verificadas antes do uso; nenhum dado sintético sem consentimento do usuário.

Por que não usar apenas o ChatGPT?

O FinAI é construído especificamente para pesquisa econômica e financeira. Veja o que ele faz que LLMs genéricos não conseguem:

Capacidade	ChatGPT / Claude (Geral)	FinAI (Especializado)
Dados financeiros A-share	Download manual, propenso a erros	✅ 43 servidores MCP com busca automática
DID com 19 verificações de robustez	Resposta genérica	✅ Erros-padrão robustos por cluster, decomposição de Bacon, estudos de evento
Modelos LaTeX JF / 经济研究	Formatação manual	✅ 30 modelos de periódicos, um comando
Estratégia de identificação causal	Sugestões genéricas	✅ Conhecimento especializado em econometria incorporado
Revisão de literatura com proveniência	Citações copiadas e coladas	✅ Rastreamento de fontes, verificação de citações
Pipeline multiestágio com checkpoints	Respostas pontuais	✅ Pipeline de 8 estágios com aprovação humana

[!TIP] Comece agora sem configuração: Abrir no GitHub Codespaces. Não é necessária instalação local.

Para usuários chineses: O guia mais completo é o 使用指南.md — um manual completo de 13 capítulos cobrindo instalação, fluxos de trabalho, fontes de dados, métodos econométricos, redação de artigos e FAQ.

---

Para Quem É Este Projeto?

Público	Caso de Uso
Estudantes de doutorado / pesquisadores	Desenhar estudos empíricos, executar análises econométricas, gerar manuscritos LaTeX para JF/JFE/RFS/经济研究/金融研究
Professores de finanças	Automatizar revisões de literatura, acompanhar experimentos de política, comparar com artigos publicados
Estudantes de pós-graduação	Aprender métodos econométricos (DID/IV/RDD) com validação automatizada e verificações de robustez
Analistas quantitativos	Acessar dados A-share, executar análise de fatores, gerar relatórios de pesquisa com padrão institucional
Pesquisadores de IA/ML	Explorar aplicações de LLM na automação de pesquisa financeira, rastreamento de proveniência, design HITL

Não tem certeza? Se você já passou dias baixando dados, rodando regressões, formatando tabelas LaTeX ou procurando trabalhos relacionados — esta ferramenta é para você.

---

Perfil do Servidor MCP: Escolha o Que se Adequa a Você

O register_mcp_servers.py suporta 4 perfis de tipo de usuário — escolha o que corresponde ao seu hardware e caso de uso:

Perfil	Servidores	Inicialização	Memória	Melhor Para
minimal	5	~1s	~30 MB	Demonstração/Ensino (Demo / Teaching) — laptops de baixo custo
academic	18	~4s	~100 MB	Estudante/Pesquisador individual (Student / Individual) — sem conta institucional
quant	30	~8s	~180 MB	Instituição/Quant (Quant / Institution) — possui Tushare/Wind/CSMAR
full	43	~12s	~220 MB	Usuário avançado (Power User) — todas as fontes de dados, RAM ≥ 16 GB

# 1) Dry-run first (推荐先看)
python scripts/register_mcp_servers.py --profile academic --prune --dry-run

# 2) Actually apply
python scripts/register_mcp_servers.py --profile academic --prune

# 3) List current registration
python scripts/register_mcp_servers.py --list

Consulte config/mcp_profiles.json para listas completas de servidores e o capítulo de instalação do 使用指南.md para instruções passo a passo.

Comportamento padrão: sem --profile, todos os 43 servidores MCP são registrados (corresponde ao perfil full). Use --prune para remover servidores fora do perfil.

---

Instalação Multiplataforma

O projeto suporta macOS, Linux e Windows com pontos de entrada específicos por plataforma:

SO	Script de Entrada	Pré-requisitos
macOS (12+)	./run.sh	Python 3.10+ (Homebrew recomendado)
Linux (Ubuntu 20.04+, Debian 11+, Fedora 35+)	./run.sh	sudo apt install python3.10 python3-venv (ou equivalente da distribuição)
Windows (10/11)	run.bat	Python 3.10+ (python.org) — marque "Adicionar ao PATH" no instalador

Escolha Seu Caminho

Este projeto suporta dois pontos de entrada — escolha o que corresponde ao seu fluxo de trabalho:

Caminho A: Agente de IA (Recomendado)

O agente de IA gerencia todo o pipeline de ponta a ponta. Não é necessário memorizar comandos.

# 1) Install once
./run.sh                    # macOS / Linux
run.bat                     # Windows

# 2) Health check
python scripts/health_check.py

# 3) Start an AI Agent (Claude Code / Cursor / Codex) and describe your research:
# "帮我研究关税政策对A股出口型企业创新的影响，设计一篇发表在经济研究的实证论文"

O agente de IA chama automaticamente todos os 8 estágios do pipeline, as fontes de dados MCP e os geradores LaTeX. Cada estágio requer sua aprovação em checkpoint antes de prosseguir.

Caminho B: CLI (Controle no Nível de Script)

Execute scripts individuais diretamente para controle refinado:

# Writing track
python scripts/agent_pipeline.py --topic "Carbon trading and green innovation" --use-hitl

# Empirical track (production modern DID)
python -m scripts.research_framework.enhanced_pipeline --topic "Carbon trading and green innovation"

# Empirical demo TWFE smoke only
python scripts/research_framework/pipeline.py --mode full --topic "Carbon trading and green innovation"

# Demo: institutional-grade financial report
python scripts/demo_research_report.py --stock 000001.SZ

# MCP tool discovery
python scripts/core/mcp_tool_market.py --search "gdp" --report

# Journal template generation
python scripts/journal_template.py --list
python scripts/journal_template.py --generate JFE output/paper.tex

Notas Específicas por Plataforma

• macOS: O Keychain é nativo; o keyring usa KeychainBackend automaticamente
• Linux: O keyring usa SecretService (gnome-keyring). Para fontes chinesas, instale fonts-noto-cjk:

  sudo apt install fonts-noto-cjk fonts-wqy-zenhei
  

• Windows: O keyring usa o Gerenciador de Credenciais. As fontes chinesas (SimHei, Microsoft YaHei) já vêm pré-instaladas

O Que Funciona em Todas as Plataformas

• ✅ Todos os pontos de entrada scripts/*.py
• ✅ 43 servidores MCP (stdlib Python puro)
• ✅ Checkpoint (fcntl.flock usa fallback para no-op no Windows)
• ✅ Testes unitários (pytest --collect-only; matriz de CI: Ubuntu + macOS + Windows; o modo daemon usa loop de polling no Windows)

Limitações Conhecidas entre Plataformas

• ⚠️ event_monitor.py usa signal.pause(), que é exclusivo do Unix; no Windows, ele usa fallback para um loop de polling
• ⚠️ keychain_setup.py é específico do macOS; para Windows/Linux, use o keyring multiplataforma via scripts/keychain_manager.py
• ⚠️ core/sandbox.py usa os.fork (exclusivo do Unix); usa fallback para subprocess no Windows
• ⚠️ event_monitor.py --daemon usa os.fork; no Windows, o daemon sai com uma mensagem amigável "use --interval 300 em vez disso" na inicialização (auditoria T2 2026-07-12)
• ✅ Sincronização de habilidades: knowledge/skills/, .claude/skills/ e .github/skills/ são mantidos em sincronia via python scripts/sync_skills.py (sem symlinks, seguro para Windows). Execute após editar qualquer documento de habilidade.
• ✅ Suporte a Codex: AGENTS.md na raiz + .agents/skills/<name>/SKILL.md por habilidade (frontmatter com name e description). Ambos sincronizados por sync_skills.py.

---

Mostre o Que Ele Faz

Descreva sua pesquisa em chinês simples — o agente cuida do resto:

帮我研究关税政策对A股出口型企业创新的影响，设计一篇发表在经济研究的实证论文

O que o agente produz automaticamente:

Estágio	Saída
Desenho de Pesquisa	Estratégia de identificação DID/IV/RDD + plano de obtenção de dados
Análise Empírica	58 módulos econométricos, testes de robustez automatizados (19 tipos)
Rascunho do Artigo	Manuscrito LaTeX no formato do periódico (JF/JFE/RFS/经济研究/金融研究/管理世界)
Ciclo de Revisão	Revisão adversarial assistida por IA com verificação obrigatória pelo pesquisador

Nota sobre números: A tabela acima descreve os estágios principais de saída do pipeline. Geração de ideias, verificação de novidade e revisão de literatura são estágios separados que ocorrem antes ou em paralelo. A contagem de servidores MCP inclui 43 servidores registrados; alguns exigem contas institucionais/pagas (Tushare Pro, Wind, CSMAR, CEIC), enquanto outros funcionam sem API keys (yfinance, akshare, Banco Mundial, FMI, OCDE, FRED, ArXiv, NBER, OpenAlex). Consulte as notas de dependência no CLAUDE.md.

Visão geral da arquitetura:

Arquitetura dupla governada: um resumo de pesquisa alimenta uma trilha de escrita e uma trilha empírica separada; checkpoints humanos, proveniência e arquivos de lacunas explícitos conectam ambas as trilhas ao pacote final de pesquisa.

Nota: Os ativos de demonstração estão em .github/demo/ e docs/assets/. O projeto é mantido ativamente.

---

Configuração do Colaborador

Checkout do código-fonte

# 1. Clone the repository
git clone https://github.com/csmar432/finai-research.git
cd finai-research

# 2. Install the package with all common optional integrations
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[extras]"
# extras includes Tushare, akshare, yfinance, MCP, dashboard, and document-processing packages.

# Optional: install econometrics packages (linearmodels, pandas-datareader, pandasql, honestdid)
pip install -e ".[econometrics]"

# 3. Configure API key (at least one required)
cp .env.example .env
# Edit .env and add: DEEPSEEK_API_KEY=sk-your-key
# Other supported: ANTHROPIC_API_KEY, OPENAI_API_KEY

# 4. Clarify the topic first (recommended)
python scripts/start_research.py --topic "碳排放权交易对企业绿色创新的影响"

# Then run the governed writing track
python scripts/agent_pipeline.py --topic "碳排放权交易对企业绿色创新的影响" --use-hitl

# Run real empirics as a separate hand-off
python -m scripts.research_framework.enhanced_pipeline --topic "碳排放权交易对企业绿色创新的影响" --explore

Números-chave (gerados automaticamente por scripts/count_assets.py):

Métrica	Contagem
Diretórios de servidores MCP	43 (28 gratuitos, 12 com API key, 0 stub, 3 opcionais)
Módulos de métodos econométricos	58
Modelos de periódicos	30
Habilidades de IA	18
Direções de pesquisa	45 registradas
Arquivos de teste / funções de teste	674 / 12.783
Módulos research_framework com testes	56/58

Execute python scripts/count_assets.py para regenerar esses números. Eles estão registrados no README como um instantâneo da contagem mais recente; o CI é a fonte da verdade.

---

Visão Geral das Ferramentas MCP

43 servidores no total: 28 funcionam sem API keys, 12 exigem API keys, 3 são de risco legal opcionais. Consulte o MCP Tool Marketplace para o catálogo completo.

Selo	Significado
💰 Pago	Exige conta institucional/paga (Tushare Pro / Wind / CSMAR / CEIC)
⚠️ Limitado	Camada gratuita disponível, mas com limite de taxa ou exigência de registro
✅ Gratuito	Sem necessidade de conta — funciona imediatamente

| MCP Server | Função | Custo | Nível Gratuito | |-----------|----------|------|---------| | user-tushare | Dados de ações A (cotações, financeiros, margem) | 💰 Pago | alternativa akshare | | user-yfinance | Ações dos EUA, ETFs, opções, financeiros | ✅ Gratuito | Completo | | user-sec-edgar | Arquivos SEC 10-K/10-Q/8-K | ✅ Gratuito | Completo | | user-financial | Macro China (PIB/IPC/M2) | ✅ Gratuito | Completo | | user-eodhd | Curva de juros dos EUA, calendário econômico | ⚠️ Limitado | Registro necessário | | user-fed-data | Federal Reserve, FOMC, Beige Book | ✅ Gratuito | Completo | | user-wb-data | API de Dados do Banco Mundial | ✅ Gratuito | Completo | | user-imf-data | Perspectivas Econômicas Mundiais do FMI | ✅ Gratuito | Completo | | user-oecd-data | Dados Econômicos da OCDE | ✅ Gratuito | Completo | | user-bea-data | Bureau of Economic Analysis (PIB dos EUA) | ✅ Gratuito | Completo | | user-eastmoney-reports | Relatórios de pesquisa, notícias, rankings de analistas | ✅ Gratuito | Completo | | user-enhanced-finance | Forex, índices de frete, commodities | ✅ Gratuito | Completo | | user-openalex | 400M+ artigos acadêmicos + grafo de citações | ✅ Gratuito | Completo | | user-arxiv | Busca e download de artigos acadêmicos | ✅ Gratuito | Completo | | user-context7 | Recuperação de texto completo para artigos (ArXiv/DOI) | ✅ Gratuito | Completo | | user-semantic-scholar | Busca de artigos aprimorada por IA | ⚠️ Limitado | Chave de API opcional | | user-nber-wp | NBER Working Papers | ✅ Gratuito | Completo | | user-brave-search | Busca na web (chinês/inglês) | ⚠️ Limitado | Registro necessário | | user-chinese-literature | Busca estilo CSSCI, CNKI | ⚠️ Limitado | Ver aviso legal em SECURITY.md |

Usuários de ações A sem contas institucionais: user-yfinance (EUA/ADR) e user-financial (nível gratuito akshare) cobrem necessidades básicas de ações e macro. Dados pagos de ações A (CSMAR/Wind/Tushare Pro) exigem contas institucionais.

Consulte Tutorial do Mercado de Ferramentas MCP para o catálogo completo.

---

Habilidades Disponíveis (18)

Cada habilidade está documentada em .claude/skills/ (Claude Code) e .github/skills/ (GitHub Copilot). No Cursor, use o comando Skill: diretamente.

Habilidade	Descrição	Módulos Principais
fin-full-pipeline	De ponta a ponta: tópico → PDF de artigo	scripts/agent_pipeline.py
fin-idea-discovery	Geração de ideias + validação de dados	idea_data_checker.py, MCP
fin-lit-review	Revisão sistemática de literatura	literature_download.py, MCP multi-fonte
fin-generate-idea	8-12 ideias ranqueadas com validação empírica	Validação de dados MCP
fin-novelty-check	Novidade vs. literatura recente (SS/OpenAlex)	NoveltyGate / --novelty-check
fin-experiment-design	Design empírico completo	modern_did.py, regression_engine.py
fin-paper-writing	Orquestração de escrita	report_generator.py
fin-paper-draft	Geração de texto do corpo (LaTeX)	journal_template.py
fin-paper-plan	Geração de esboço	30 modelos de periódicos
fin-paper-figure	Geração de gráficos (≥300 DPI)	fin_charts.py, chart_factory.py
fin-paper-convert	Compilação LaTeX	xelatex/pdflatex + modelos de periódicos
fin-review-loop	Revisão adversarial multi-rodada	Pontuação em 5 dimensões
fin-submit-check	Lista de verificação pré-submissão	Auditoria de formato, DPI, citações
fin-data-acquisition	Busca de dados + scripts de regressão	43 servidores MCP
fin-brief-generator	Geração automática de FIN_BRIEF.md	5 ferramentas aprimoradas
fin-ref-paper	Gerenciamento de referências BibTeX	API CrossRef DOI
fin-viz-launch	Linguagem natural → gráficos acadêmicos	chart_pipeline.py, 20+ tipos

---

Tutoriais

Tutorial	Descrição	Tempo
01 - Início Rápido	Configuração e execução do seu primeiro pipeline	5 min
02 - Relatórios Financeiros	Gere relatórios de pesquisa institucional	10 min
03 - Direções de Pesquisa	Projete estudos empíricos com DID/RDD/IV	15 min
04 - Mercado MCP	Descubra e adicione ferramentas MCP	15 min
05 - Pesquisa Orientada a Eventos	Automatize pesquisa via monitoramento de eventos	20 min

---

Documentação

Documento	Descrição
SETUP_GUIDE.md	Configuração de ambiente, chaves de API, Docker
使用指南.md	Guia de uso completo (chinês)
docs/tutorials/01-quickstart.md	Início rápido de 5 minutos
CLAUDE.md	Configuração e capacidades do agente
CONTRIBUTING.md	Diretrizes de contribuição
docs/tutorials/	Tutoriais passo a passo
docs/api_reference.md	Documentação da API
docs/MOCK_DATA_POLICY.md	Política de dados simulados (5 servidores desativados por padrão)
docs/DOCKER_INSTALL.md	Guia de instalação do Docker
docs/CITATION_GUIDE.md	Orientação de citação para trabalhos derivados
docs/GITHUB_DISCUSSIONS_SETUP.md	Ativação do GitHub Discussions
docs/ARCHITECTURE.md	Visão geral da arquitetura do sistema

---

Comandos Comuns

# Paper pipeline
python scripts/research_framework/pipeline.py --topic "碳排放权交易对企业绿色创新的影响"

# Financial report
python scripts/demo_research_report.py --stock 000001.SZ

# MCP tool marketplace
python scripts/core/mcp_tool_market.py --search "gdp" --report

# Event monitor
python scripts/event_monitor.py --interval 300 --test

# Literature review
python scripts/literature_download.py "carbon trading innovation" --source arxiv,semantic,openalex --limit 20

# Or use an AI Agent directly
# "帮我做碳交易创新领域的文献综述"

# Journal template
python scripts/journal_template.py --list
python scripts/journal_template.py --generate JFE output/paper.tex

# Dashboard
streamlit run scripts/dashboard.py --server.port 8050

---

Cobertura de Dados

Mercado	Fonte	Tipos de Dados
Ações A	user-tushare (gratuito)	Cotações diárias, financeiros, margem, fluxo norte
Ações dos EUA	yfinance + Finviz (gratuito)	Cotações, financeiros, ESG, opções, arquivos SEC
Macro (Global)	World Bank + IMF + OECD (gratuito)	PIB, IPC, população, comércio, dívida
Macro (China)	user-financial + NBS (gratuito)	IPC, PPI, PMI, M2, FDI, vendas no varejo
Macro (EUA)	FRED + BEA + Fed (gratuito)	NIPA, FOMC, Beige Book, curva de juros
Renda Fixa	EODHD (chave) / user-financial (gratuito)	Rendimentos de títulos, preços de títulos, spreads de crédito
Forex e Commodities	user-enhanced-finance + user-financial (gratuito)	Taxas de câmbio, índices de frete, metais preciosos
Relatórios de Pesquisa	东方财富 (gratuito)	Relatórios de analistas, notícias, análise setorial
Acadêmico	arXiv + NBER (gratuito)	Working papers, citações

---

Estendendo o Sistema

Adicionando um Novo Servidor MCP

1. Crie o diretório: mcp_servers/user_your_server/
2. Adicione SERVER_METADATA.json
3. Adicione definições de ferramentas em tools/*.json
4. Registre nas configurações MCP do Cursor
5. Reconstrua o registro: python scripts/core/mcp_tool_market.py --dir mcp_servers

Consulte Tutorial do Mercado MCP para o guia completo.

Adicionando uma Nova Direção de Pesquisa

1. Crie o arquivo: scripts/research_directions/carbon_economics.py (copie de uma direção existente como green_finance.py como modelo)
2. Defina a classe ResearchDirection com:
   • Perguntas de pesquisa
   • Requisitos de dados
   • Derivação de hipóteses
   • Estratégia empírica
3. Adicione a scripts/research_directions/__init__.py

---

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Faça commit das alterações (git commit -m 'Add amazing feature')
4. Envie para o branch (git push origin feature/amazing-feature)
5. Abra um Pull Request

Consulte CONTRIBUTING.md para as diretrizes completas.

---

Licença

Este projeto é licenciado sob a Licença MIT. Consulte LICENSE para detalhes.

---

Agradecimentos

• O modo de clarificação interativa de 5 rodadas é baseado no design do Night Owl Research Agent (renomeado em 27/06/2026)
• Inspirado pela arquitetura multi-agente do PaperOrchestra
• Dados fornecidos por akshare, yfinance, World Bank API e Tushare Pro

---

Histórico de Estrelas

---

Construído Com

Camada	Tecnologia
Orquestração de IA	Claude Code / Cursor / Codex, Claude API, OpenAI API, Anthropic API
Dados (43 servidores)	user-tushare, user-yfinance, user-financial, user-sec-edgar, user-eastmoney-*, World Bank API, IMF API
Econometria	statsmodels, linearmodels, scipy
Visualização	matplotlib, seaborn, plotly
Pipeline	Python 3.10+
Testes	pytest, ruff
Documentação	MkDocs Material
Containerização	Docker, Docker Compose

---

Diagramas de Arquitetura

Trilha de Escrita (5 Artefatos + Pontos de Verificação Humanos)

Nota de trilha dupla: Escrita (agent_pipeline.py) tem 5 estágios (esboço → literatura → plotagem → escrita → refinamento) com HITL opcional. A parte empírica é uma transferência separada: enhanced_pipeline / modern_did para estimadores reais; research_framework/pipeline.py é apenas demonstração TWFE + estrutura de design. Consulte docs/ARCHITECTURE.md §0.

Roteamento de Dados (43 diretórios: 28 sem chave + 12 com chave de API + 3 com adesão legal opcional)

Painéis empíricos locais são verificados primeiro. Uma variável exata ausente interrompe visivelmente; não aciona uma substituição não anunciada por dados sintéticos ou proxy.

Seleção de Estimador DID Moderno

O estimador segue o momento do tratamento, a disponibilidade do grupo de comparação e o estimando alvo. TWFE permanece como uma linha de base diagnóstica, não como prova automática de identificação.

---

Como o FinAI se Encaixa no Ecossistema

O FinAI foca no fluxo de trabalho de ponta a ponta da pesquisa empírica em economia e finanças: ideia de pesquisa → revisão de literatura → design empírico → aquisição de dados → análise → rascunho do artigo → submissão.

Bibliotecas gerais de inferência causal (ex.: dowhy, StatsPAI, diff-diff) focam na camada de algoritmo de IC. O FinAI foca na camada de fluxo de trabalho de pesquisa que envolve dados, econometria, modelos de periódicos e portões de intervenção humana em um único pipeline.

Esse foco traz recursos complementares para economistas:

• 43 fontes de dados MCP para financeiros de ações A (Tushare/CSMAR/Wind), ações dos EUA (yfinance), macro global (FRED/World Bank/IMF/OECD/BEA) e 400M+ artigos acadêmicos (OpenAlex/ArXiv).
• 58 módulos de métodos econométricos, incluindo DID escalonado moderno (Callaway-Sant'Anna, Sun-Abraham, Borusyak), controle sintético/DiD, IV/2SLS, GMM em painel, RDD, tripla diferença, quantil em painel, regressão espacial, etc.
• 30 modelos de periódicos (EN+ZH+JP+DE) cobrindo JF / JFE / RFS / JPE / Econometrica / 经济研究 / 金融研究 / 管理世界 / 会计研究 / ZWiSt / JNS e mais.
• Portões de intervenção humana em cada estágio do pipeline para prevenir alucinações de LLM.

Consulte Projetos Relacionados abaixo para ferramentas que funcionam junto com o FinAI.

---

Mantenedor

Este projeto é mantido por @csmar432.

• 🐛 Relatórios de bugs e solicitações de recursos: GitHub Issues
• 💬 Perguntas e ideias: GitHub Discussions
• 🔒 Divulgações de segurança: GitHub Security Advisories
• 💖 Patrocinar / apoiar: GitHub Sponsors · 爱发电

Contribuições de todos os tamanhos são bem-vindas — consulte CONTRIBUTING.md para o fluxo de trabalho.

Cite Este Trabalho

Se este projeto ajudar sua pesquisa, dê uma ⭐ — isso mostra a outros economistas que o projeto vale seu tempo.

Se você usar o FinAI Research Workflow em pesquisa publicada, cite-o como:

@software{finai2026,
  title  = {FinAI Research Workflow: An End-to-End AI Agent Pipeline for Economic and Financial Research},
  author = {csmar432},
  year   = {2026},
  month  = jun,
  url    = {https://github.com/csmar432/finai-research},
  note   = {GitHub repository. For a permanent DOI, publish on Zenodo and update this field.}
}

Projetos Relacionados

• dowhy — biblioteca de inferência causal (8,2 mil ⭐)
• StatsPAI — kit de ferramentas de inferência causal nativo de agente (274 ⭐)
• moderndid — DiD moderno acelerado por GPU (25 ⭐)
• diff-diff — DiD estilo sklearn em Python (280 ⭐)
• PaperOrchestra — escrita de artigos multi-agente do Google (82 ⭐)
• E2ER-project — pipeline de pesquisa empírica de ponta a ponta (1 ⭐)
• econ-paper-studio — CLI nativo de agente para economia empírica (2 ⭐)

Licença MIT — consulte LICENSE para o texto completo.