cmoralesm/P123-Claude-Skill

Portfolio123 (P123)

Portfolio123 é uma plataforma web para pesquisa sistemática de ações: screaning, sistemas de ranking multifator, simulação/backtesting de estratégias e uma API REST. Sua linguagem de fórmulas (não Python) é usada em regras de screen, nós de sistemas de ranking, regras de compra/venda e extrações de dados da API.

Tudo nesta skill foi extraído do Factor Reference oficial do P123 em 09/06/2026 (4.463 fatores e 465 funções em 13 categorias, além de 473 constantes/IDs de séries/operadores) e da especificação OpenAPI oficial e do código-fonte do wrapper p123api. Nunca invente um nome de fator ou função - se um nome não estiver nesses arquivos de referência, presuma que ele não existe e procure o nome correto.

Qual arquivo de referência ler

Leia apenas o que a tarefa necessita:

Tarefa	Leia
Chamadas à API REST ou ao p123api Python (auth, screen_run, backtests, rank_ranks, data_universe, uploads, AI Factor)	references/api.md
Índices de valuation (PE, EV/EBITDA, preço-sobre-X), margens, taxas de crescimento, scores de qualidade (Piotroski), razões financeiras e por ação	references/ratios-statistics.md
Itens de demonstrações financeiras (DRE, balanço patrimonial, fluxo de caixa) e suas variantes de fator; mapeamento de fornecedores Compustat/FactSet	references/financials.md
Metadados da empresa, preços/dividendos/desdobramentos como fundamentos, estatísticas de ações, participação de insiders/institucionais, juros de venda a descoberto, dados realizados	references/fundamentals.md
Estimativas de analistas: consenso EPS/vendas (famílias CurFY/NextFY/CurQ), revisões, surpresas, recomendações, crescimento de longo prazo	references/estimates.md
Indicadores de preço/volume: SMA/EMA, RSI, MACD, ADX/DMI, Bollinger, retornos (Ret%Chg), estatísticas de 52 semanas, volatilidade, beta	references/technical.md
Ferramentas transversais e de séries temporais: FRank, FHist, FHistAvg, Aggregate, FMedian/FSum/FCount, funções Loop, regressão linear, condicionais	references/advanced-functions.md
Contexto de estratégia simulada: fatores de regras de compra/venda (Rank, RankPos, estado do portfólio), padrões de regras, expressões idiomáticas de rebalanceamento	references/strategy.md
Agregados de todo o universo: UnivAvg, UnivCnt, UnivMedian, UnivSum, ...	references/universe-operations.md
Filtros de definição de universo: UnivExclude, UnivSubset, UnivRBICS	references/universe-filters.md
Acesso a séries de benchmark: BenchClose	references/benchmark-functions.md
Classificação setorial/industrial (RBICS): Sector, IndCode, SubIndustry, composites setoriais/industriais	references/industry-sector.md
Vocabulários de taxonomia de ETFs (contextos ETF): classe de ativo, país, região, conjuntos setoriais	references/taxonomy.md
Utilitários matemáticos/conjuntos/data, InList, GetSeries, IDs de séries macro (##CPI, mapeamentos FRED), constantes de país e ID de universo, operadores	references/misc.md
Replicação de um fator acadêmico nomeado (Piotroski F-Score, rentabilidade bruta Novy-Marx, accruals Sloan, Beneish M-Score, momentum 12-1, betting-against-beta, crescimento de ativos, emissão líquida de ações): implementação exata, direção e escopo do nó, armadilhas de tradução	references/factor-replication.md
Gerar ou editar XML de sistema de ranking (leitura obrigatória, veja abaixo)	references/ranking-system-xml.md
Executar os scripts de exemplo inclusos (configuração, variáveis de ambiente, modelo de segurança)	scripts/README.md

Fundamentos da linguagem de fórmulas

// Variáveis: SetVar SEMPRE retorna VERDADEIRO (1), nunca o valor atribuído
SetVar(@cheap, PEExclXorTTM < 15)   // regra própria, depois reutilize @cheap em regras posteriores
// Retornar 1 é o que permite que uma definição seja encadeada na fórmula que a usa -
// a única opção onde não há regra seguinte (nós de ranking, fórmulas da API):
SetVar(@r, Ret%Chg(252, 21)) * @r * Abs(@r)   // 1 * @r * Abs(@r) == @r * Abs(@r)
// Uma regra de venda SetVar pura sempre aciona a venda - negue-a: !SetVar(@x, ...).
// @var:expr difere - RETORNA o valor (pode ser 0/NA) e adiciona uma coluna de relatório:
MktCap > @med:FMedian("MktCap")

// Matemática: + - * / e ^ (potência). ^ tem precedência sobre todos os outros operadores, então 2*x^3 é 2*(x^3).
// x^y e Pow(x, y) são a mesma operação - escreva x^y. NÃO existe Sqrt: uma raiz
// quadrada é x^0.5, uma raiz n-ésima x^(1/n) (parênteses obrigatórios, pois x^1/3 significa (x^1)/3).
MktCap^0.5                          // raiz quadrada da capitalização de mercado; NÃO Sqrt(MktCap)

// Condicional: Eval(condição, valor_se_verdadeiro, valor_se_falso)
Eval(PEExclXorTTM = NA, Pr2SalesTTM < 2, PEExclXorTTM < 20)

// Tratamento de NA: IsNA(expr1, expr2) é uma função de SUBSTITUIÇÃO (retorna expr2 quando
// expr1 é NA). NÃO é um teste booleano de um argumento - teste NA com "= NA".
IsNA(DivPSTTM, 0)           // dividendo por ação, 0 quando ausente
LastSellPrice = NA          // booleano: nunca vendido antes

// Percentil transversal (0-100). Padrões: escopo #All, ordenação #DESC, NAs #InclNA
FRank("PEExclXorTTM", #All, #ASC) > 80   // #ASC: PE baixo classifica alto

// Histórico pontual: valor de uma fórmula N semanas atrás / amostras médias
FHist("ROE%TTM", 52)
FHistAvg("ROE%TTM", 4, 13)

// Técnicos: barras são dias de negociação; constantes #Year, #Month, #Week são contagens de barras
Close(0) > SMA(200, 0)
RSI(14) < 30
Ret%Chg(252, 21)            // retorno total em 252 barras, terminando 21 barras atrás

// Agregados de escopo e contrapartes
Aggregate("Pr2SalesTTM", #Industry)      // métodos: #Avg (padrão), #CapAvg
FMedian("Pr2SalesTTM", #Industry)        // mediana; também FSum, FCount
UnivCnt("PEExclXorTTM < 10")             // contagem em todo o universo

// Séries macro/índices em funções de preço via IDs de série
Close(0, ##CPI)
Close(0, GetSeries("$SP500"))

Padrão de itens de linha (Financeiros). Cada item de linha de demonstração financeira é uma função mais variantes de fator pré-construídas: Sales(offset, type[, NAHandling]) com type = QTR/ANN/TTM e NAHandling = FALLBACK (padrão), KEEPNA, ZERONA; variantes pré-construídas anexam sufixos de período à mesma base - SalesQ, SalesPQ, SalesPYQ, SalesTTM, SalesPTM, SalesA, SalesPY, crescimento SalesGr%TTM/SalesGr%A, por ação SalesPSQ, médias Sales5YAvg, regressões SalesRegGr%TTM. O mesmo sistema de sufixos impulsiona a maioria dos 4.463 fatores - veja references/financials.md.

Screens vs rankings. Regras de screen são testes booleanos avaliados por ação. Sistemas de ranking combinam nós de fator ponderados em uma classificação de 0–100; em um nó de ranking, "menor é melhor" controla a direção (por exemplo, PE), enquanto em FRank o equivalente é o argumento de ordenação #ASC.

Crítico: não alucine nomes

O modo de falha mais comum é inventar nomes de fatores com aparência plausível. Principais armadilhas entre categorias (cada nome "correto" verificado no dicionário de extração; tabelas por categoria estão na seção Erros Comuns de cada arquivo de referência):

Errado (não use)	Correto	Nota
IsNA(x) como booleano	x = NA	IsNA(expr1, expr2) é uma substituição de dois argumentos
Eval(IsNA(x), a, b)	Eval(x = NA, a, b)	mesma armadilha dentro de Eval
Eval(SetVar(@x, f), A, NA)	SetVar(@x, f) * A	SetVar retorna VERDADEIRO; o ramo NA é código morto
PiotroskiF	PiotFScore	Piotroski F-Score
EstEPSCY / EstEPSCQ	CurFYEPSMean / CurQEPSMean	a família de estimativas legada Est... não existe
Revenue	Sales	item de linha de receita
NetIncome	NetIncBXor	lucro líquido antes de extraordinários
TotalAssets	AstTot	ativos totais
FreeCashFlow	FCF	fluxo de caixa livre
MarketCap	MktCap	capitalização de mercado
EnterpriseVal	EV	valor da empresa (por ação: EVPS)
GrossMargin	GMgn%	margem bruta (ex.: GMgn%TTM)
CurrentRatio	CurRatio	liquidez corrente
DivYield%TTM	Yield	rendimento de dividendos não leva sufixo de período
EarnYield%TTM	EarnYield	rendimentos são figuras de preço atual, sem sufixo
PEG	PEGLT / PEGST	variantes da razão PEG
AltmanZ	AltmanZOrig	também AltmanZPriv, AltmanZNonManu
LatestRank	Rank	classificação atual em regras de compra/venda
SectorCount	SecCount	contagem de posições no setor
UnivCount	UnivCnt	contagem do universo
BenchmarkClose	BenchClose	fechamento do benchmark
Average / Ln	Avg / LN	grafias de funções matemáticas
Power / Pow(x, y)	x^y	^ é o operador de potência; Pow é o equivalente verboso
Sqrt(x) / Exp(x)	x^0.5 / 2.718281828^x	não há função raiz ou exp; ^ é o operador de potência
PlusDI / MinusDI	DMIPlus / DMIMinus	indicadores direcionais
IndustryCode	IndCode	fator de classificação

Quando estiver em dúvida sobre qualquer nome, pesquise no arquivo de referência relevante antes de escrevê-lo.

XML de sistema de ranking: sempre leia a referência primeiro

SEMPRE leia references/ranking-system-xml.md antes de gerar ou editar qualquer XML de sistema de ranking. O esquema correto NÃO é adivinhável, e versões anteriores desta skill entregaram um quebrado. Esse arquivo contém o esquema validado, orientação de direção RankType, semântica de peso de nó (incluindo quando Weight="0" é legal), um exemplo trabalhado de Penman & Pope e uma tabela de erros de fórmula conhecidos. Em particular: Weight="0" e um Weight omitido em um nó de ranking são legais, nunca um erro para corrigir - leia esse arquivo para saber como o peso é então dividido.

Início rápido da API

As credenciais vêm de Configurações da Conta P123 → API (assinatura paga necessária). Os scripts inclusos as leem das variáveis de ambiente P123_API_ID / P123_API_KEY.

import p123api

with p123api.Client(api_id='seu api id', api_key='sua api key') as client:
    try:
        # Screen por definição. Screens apenas long: regras são fórmulas simples -
        # NÃO adicione um 'type' por regra (é rejeitado para o método 'long').
        df = client.screen_run({
            'screen': {
                'type': 'stock',
                'universe': 'SP500',
                'method': 'long',
                'maxNumHoldings': 25,
                'ranking': {'formula': 'PEExclXorTTM', 'lowerIsBetter': True},
                'rules': [
                    {'formula': 'MktCap > 1000'},
                    {'formula': 'ROE%TTM > 10'},
                ],
            },
            'asOfDt': '2026-01-05',
        }, to_pandas=True)

        # Download de fatores em massa para pesquisa/ML
        df2 = client.data_universe({
            'universe': 'SP500',
            'asOfDts': ['2026-01-05'],
            'formulas': ['PEExclXorTTM', 'ROE%TTM', 'MktCap', 'Ret%Chg(252, 21)'],
            'includeNames': True,
            'precision': 4,
        }, to_pandas=True)
    except p123api.ClientException as e:
        print(e)

As respostas carregam cost e quotaRemaining - monitore-os; veja api.md → Quotas & Costs. Para documentação endpoint por endpoint, o mapa do wrapper de 44 métodos, uso do AI Factor (o asOfDt histórico deve ser um sábado) e armadilhas conhecidas (includeNodeDetails obsoleto → nodeDetails, payloads de upload via data=, o bug type por regra), leia references/api.md.

Exemplos executáveis

scripts/ contém 9 exemplos de linha de comando construídos em p123_helpers.py (instalação: pip install "p123api[pandas]" - desde p123api 3.0, pandas é um extra, não uma dependência). Todos são somente leitura, exceto 09_strategy_rebalance_dryrun.py, que só muda algo com uma flag --execute explícita mais confirmação digitada. Comece com 01_auth_check.py, depois 02_screen_run.py, 07_price_history.py (padrão para IBM, uma das três tickers nomeadas pela isenção de licença POST /data da especificação). Tabela completa e modelo de segurança: scripts/README.md.

Pontos de partida de fatores verificados por estilo

Estilo	Fatores/funções verificados
Valor	PEExclXorTTM, Pr2BookQ, Pr2SalesTTM, Pr2FrCashFlTTM, EV2EBITDATTM, EarnYield, FCFYield
Momentum	Ret%Chg(252, 21), Ret%Chg(231, 21) (12-1), Pr52W%Chg, Pr52WRel%Chg, RSI(14)
Qualidade	ROE%TTM, ROA%TTM, GMgn%TTM, OpMgn%TTM, PiotFScore
Baixa volatilidade	TRSD1YD, PctDev(52, 5), Beta1Y (= BetaFunc(5, 52, 0))
Tamanho / liquidez	MktCap, AvgDailyTot(63)
Crescimento	SalesGr%TTM, EBITDAGr%TTM, CurFYEPSMean vs tendências NextFYEPSMean

Estes são pontos de partida, não construções. Quando o usuário nomear um fator publicado - Piotroski, rentabilidade bruta Novy-Marx, accruals Sloan, Beneish, momentum 12-1, betting-against-beta, crescimento de ativos, emissão líquida de ações - leia references/factor-replication.md primeiro: ele fornece a implementação exata, a direção e escopo do nó e as armadilhas que silenciosamente constroem um fator diferente (Ret%Chg(252, 21) abrange treze meses, não 12-1; um múltiplo de preço classificado como menor-é-melhor promove empresas com prejuízo ao topo).

Regras de trabalho para esta skill

1. Verifique cada nome de fator/função nos arquivos de referência antes de usá-lo; nunca extrapole de uma família de nomes para outra (as regras de sufixo diferem por família).
2. Leia ranking-system-xml.md antes de qualquer trabalho com XML de ranking - sem exceções.
3. Para nomes de parâmetros da API, api.md reflete o código-fonte do wrapper onde a especificação discorda (ex.: passe api_id/api_key como strings mesmo que a especificação tipifique apiId como inteiro).
4. Sufixos de período: Q, PQ, PYQ, TTM, PTM, A, PY são a família principal; crescimento e sufixos estatísticos (Gr%..., RSD%..., RegEst..., ...3YAvg) existem apenas onde um ... (truncado para tradução, mas o conteúdo permanece inalterado).