Busca de clientes mais eficiente
e automática com IA.
O SocialSelling responde a uma única pergunta — "Quem devo abordar primeiro?" — produzindo um ranking explicável de prospects que aprende com o feedback da operadora. Este documento é o overview do projeto e, ao mesmo tempo, um modelo das boas práticas de desenvolvimento e implementação adotadas até aqui.
1 Visão & escopo
O produto torna a prospecção eficiente e automática: dado um ICP (Ideal Customer Profile), o sistema descobre candidatos, infere dados estruturados, pontua o fit/intent/confiança, entrega Lead Cards ranqueados com justificativa (XAI) e aprende com os votos 👍/👎 da operadora.
No escopo
- Ranking explicável de prospects (fit · intent · confiança)
- Descoberta + enriquecimento incremental de leads
- Justificativa estruturada (drivers +/− e sinais ausentes)
- Aprendizado por feedback like/dislike (ADR-007)
- Cockpit web local (visualização, edição de pesos, votos)
Fora do escopo (guardrails)
- CRM, automação de outreach/mensageria, cadências
- Banco de dados, Redis, Celery, Docker, AWS/Terraform
- Scraping de Instagram/LinkedIn
- Geração automática de mensagens de outreach
2 Arquitetura do PoC
Um único processo Python 3.11+, sem servidor obrigatório,
sem banco, sem fila.
Persistência em JSON atômico (write-temp + os.replace).
O único custo variável são os tokens de duas APIs de cognição/busca.
Pipeline determinístico (módulos, não agentes de runtime)
M3 e M4 são funções puras: mesma entrada → saída byte-idêntica. O orquestrador injeta clientes, cache, relógio e config.
Módulos de suporte
w_fit/w_intent
a partir de votos 👍/👎 (ADR-007).
entity_id) (ADR-006).
Sensores externos
Tavily
Busca aberta (M1). Snippets sociais e sinais de intenção.
Gemini (gemini-2.5-flash / flash-lite)
Cognição (M2). Extrai entidades estruturadas + persona/intenção em lotes.
Apollo.io ADR-004
Firmografia B2B. Escada incremental; API master exige plano pago (Free bloqueia p/ entitlement).
3 Camadas semânticas & regras invioláveis
A correção do sistema repousa sobre quatro invariantes. Elas valem para todo código novo — inclusive os sensores, a camada de volume e o módulo de aprendizado.
① Isolamento de camadas
Uma inferência jamais é tratada como evidência. Sem
referências mutáveis compartilhadas. Apollo vira ObservedEvidence, nunca inferência. O feedback (ADR-007)
opera apenas na camada de apresentação — nunca toca Evidence ou Inferences.
② Determinismo byte-idêntico
Mesma memória → mesma saída. Relógio e RNG injetados; IDs por hash estável; tie-break estável. O modelo de feedback usa gradiente full-batch sem aleatoriedade — mesmo log ⇒ mesmos pesos, bit a bit.
③ Open-World
Ausência de sinal = incerteza (↑u), nunca falso. Missing Evidence é explícito; falhas degradam, não
quebram. Dislike é sinal de treino — o lead permanece visível, com selo.
④ Persistência atômica
Toda escrita é write-temp + os.replace. Nunca um arquivo meio-escrito — vale para
cache, corpus, ledgers e o store de feedback.
4 Decisões arquiteturais (ADRs)
Cada decisão consciente vira um ADR versionado e referenciável. A fonte da verdade é o ADR-000; os demais são emendas explícitas.
Escopo canônico do PoC local
Fixa SDD v1.0 como espinha; database-less; Tavily+Gemini; M1–M5 como pipeline.
Camada de intenção: hipóteses
Intent = Σ priors das hipóteses ativadas; desqualificadores zeram o lead (hard filter).
UI de operador local (FastAPI)
Cockpit web: tabela densa de leads, drawer de detalhes, aba de pesos, botões 👍/👎 de feedback.
Orquestração paralela (LangGraph) + FinOps
Motor async opcional para colheita multi-provedor e poda precoce. Diferido por design.
Apollo.io como 2º sensor firmográfico
Escada de enriquecimento incremental: descoberta → org-enrich → reveal por crédito. API master exige plano pago.
Reforma cognitiva: lotes + orçamento RPD
Extração em lotes eleva o teto Gemini; orçamento de requisições/dia + ondas resumíveis.
Corpus de leads acumulativo
Runs acumulam (upsert idempotente por entity_id). A onda só avança quando o ciclo produz leads — evita queimar cache sem resultado.
Aprendizado por feedback like/dislike
Regressão logística (Python puro, sem dependências)
reajusta w_fit/w_intent a partir dos votos. Auto-apply com 4 travas: gate
de amostra, L2, shrinkage e clamp. Opt-in via [learning].enabled.
5 Especificações de desenvolvimento (SDDs)
Cada ADR não-trivial vem acompanhado de uma SDD (Spec-Driven Development): contratos, cenários, plano de testes e WUs. Spec-first — o documento precede o código.
SDD · Apollo (busca + enriquecimento incremental)
Escada de crédito, ledger mensal, cache por volatilidade, degradação Open-World.
SDD · Orquestração paralela + FinOps (LangGraph)
Colheita concorrente, poda precoce, modos degradados. Motor opcional.
SDD · Operator Cockpit (UI)
Data grid de alta densidade, drawer de lead, aba de pesos e botões de feedback 👍/👎.
SDD · Lead Results Table UX
Padrão "scan-then-focus": tabela densa + drawer slide-over. Refinamento visual do cockpit v2.
Roadmap · Escala de volume de leads
Teoria das restrições, os 4 pilares e o status de implementação.
6 Boas práticas de desenvolvimento
É aqui que o projeto pretende ser modelo: a complexidade vive no processo de construção, não no sistema. O PoC permanece enxuto; a disciplina é total.
SDD-to-Code Loop (obrigatório por módulo)
- 1Contrato Pydantic
- 2BDD + fixtures
- 3Implementação mínima
- 4Gate verde
- 5PR + auto-merge
Modo operacional: Dia vs. Noite (L-057)
☀️ Sessão de dia (interativa)
Especifica e gera cards — não desenvolve o produto. Autoria de ADRs, SDDs, docs, tooling e curadoria do board. Card só vai para Todo com DoR 100% (Gherkin, fixtures, sem ambiguidade).
🌙 Run noturno (autônomo)
Consome a coluna Todo via skill github-sdd-sync. Revalida DoR, implementa, exige DoD
(gate verde, PR CI-verde, PROGRESS e lições atualizados).
Quality Gate inegociável
ruff + mypy --strict + pytest
100% verde e determinístico. Flakiness = falha.
Git: branch → PR → auto-merge
Nunca commit direto na main. CI obrigatório; merge só com gate verde. Squash + delete-branch.
Tags = pontos de restauração
Cada WU verde recebe uma tag anotada. Rollback público
via git revert, nunca reset/force.
APIs sempre mockadas
Testes nunca tocam rede: fixtures gravadas + fakes.
Tolerância numérica 1e-9. Erros de API surfaciados ao
usuário (nunca silenciosos — L-057).
Opt-in = paridade
Toda feature nova entra desligada por padrão → o baseline
permanece byte-idêntico (smoke E2E). [learning].enabled,
[apollo].enabled, [corpus].enabled.
FinOps por ledger atômico
Orçamentos de crédito (mensal) e de requisições (diário)
persistidos; try_spend/refund/reconciliação. Erros de billing (429) propagam a
mensagem crua até o frontend.
Comando de gate (Windows)
.venv\Scripts\python.exe -m ruff check . # lint
.venv\Scripts\python.exe -m mypy # tipos (strict)
.venv\Scripts\python.exe -m pytest -q # 150+ testes determinísticos
# Ou: .\scripts\gate.ps1 (roda os três em sequência)7 Estratégia de volume (rodando local)
Objetivo: buscar muito mais leads sem sair do local/database-less. Aplicou-se Teoria das Restrições ao funil — ampliar descoberta sem elevar o teto cognitivo só faz bater no muro mais rápido. Daí os quatro pilares.
| Pilar | O que faz | Estado |
|---|---|---|
| A · Teto cognitivo | Extração em lotes + orçamento RPD + ondas resumíveis (ADR-005) | ✅ core |
| B · Corpus acumulativo | Runs acumulam; upsert idempotente; onda avança só com resultado (ADR-006) | ✅ core |
| Apollo · Descoberta | People Search + org-enrich + reveal (ADR-004) — API master exige plano pago | ✅ implementado |
| C · Estado escalável | JSON monolítico → NDJSON/shards (sem banco) | ⏸ diferido |
| D · Entity resolution | Domínio canônico + exclusão de vendors + dedup cross-provider | ⏸ diferido |
Tudo opt-in ([apollo].enabled
· [corpus].enabled · [gemini].rpd_enabled). Diferidos com razão documentada — não há
refino arriscado por completude.
8 Processo de auto-aprendizagem
Ao final de cada tarefa, os aprendizados são destilados em docs/licoes-aprendidas.md
(formato L-NNN | Categoria | Lição | Como aplicar) e em memória
persistente. Hoje são
57 lições que retroalimentam decisões futuras — o projeto
fica mais inteligente a cada ciclo.
Injetar relógio e derivar IDs por hash estável — nunca
UUID aleatório nem datetime.now() interno. Garante
reexecução byte-idêntica. Também vale para o modelo de feedback (full-batch sem random).
Fan-out com asyncio.gather(return_exceptions=True) + tratar exceção
crua: um provedor não derruba o lote.
Container fixed inset-0 z-50 fechado precisa de pointer-events:none; sem isso uma camada invisível engole
todos os cliques sem erro visível.
Regressão logística com gradiente full-batch, init em
zeros, amostras ordenadas por company_id e sem random → mesmo feedback.json ⇒ mesmos pesos, bit a bit.
Avançar a onda só quando o ciclo produz leads. Avançar à toa "queima" queries cacheadas e escondia que a causa-raiz era billing do Gemini (corrigido na L-057).
429 do Gemini era prepayment credits depleted,
não cota free-tier. GeminiClient agora surfacia o error.message cru; o endpoint retorna 502 com mensagem
acionável (link de billing).
9 Mapa de versões (pontos de restauração)
Fundação CI-verde: toolchain, contratos, planejamento.
PoC funcional: pipeline M1→M5 + smoke E2E byte-idêntico.
Motor de intenção (hipóteses), Lead Card acionável, UI de operador, precisão de persona.
Fundação de volume: schemas Apollo, ledgers de crédito/RPD, corpus; descoberta Apollo fim-a-fim.
Specs de volume completas: escada Apollo (1/2/3), batch+RPD, corpus acumulativo. 120 testes verdes.
Cockpit v2 (tabela densa + drawer), degradação de billing com mensagem acionável (L-057), busca incremental por ondas.
Aprendizado por feedback (ADR-007): regressão
logística determinística, store de votos atômico, auto-apply de pesos com 4 travas. 150+
testes verdes. Módulos: learning/ (model, tuner,
feedback_store, schemas).
Como ligar o volume + aprendizado (run real)
# 1) runtime.toml
[apollo].enabled = true [corpus].enabled = true
[gemini].rpd_enabled = true [learning].enabled = true
# 2) gravar fixtures (supervisionado — Apollo master exige plano pago)
.venv\Scripts\python.exe scripts\record_apollo_fixtures.py
# 3) rodar o pipeline
.venv\Scripts\python.exe -m socialselling.orchestrator --icp config\icp_criteria.talita.json
# 4) cockpit web (marcar likes/dislikes → reajusta pesos automaticamente)
.venv\Scripts\python.exe -m socialselling.web # → http://127.0.0.1:800010 Planejamento & operação do desenvolvimento
O projeto adota um modelo de governança que separa autoria de especificação (interativa, feita de dia) de execução de implementação (autônoma, feita à noite). Isso otimiza a cota do Claude Code Pro e mantém a integridade do repositório — o dono usa o dia para pensar e evoluir o sistema; o desenvolvimento roda no run agendado.
Fluxo do board (GitHub Project #1)
Card bloqueada (DoR incompleto ou gate vermelho após 2
tentativas) → BLOCKED: no PROGRESS.md e devolve ao Backlog. Nunca adivinha — para e
reporta.
Sessão de dia — autoria
- 1.Entender o que o dono quer evoluir (e o porquê).
- 2.Rascunhar cards usando o template de DoR/DoD.
- 3.Cobrar o DoR — perguntar ao dono por cada item faltante (Gherkin, fixtures, contrato, escopo). Nunca empurrar card incompleta.
- 4.Card com DoR 100% → mover para Todo (só humano faz isso).
- 5.Evoluções grandes → quebrar em várias cards pequenas (1 WU cada).
Run noturno — execução autônoma
- S1.Ler
.ai/state/PROGRESS.md+ card em Todo de maior prioridade. - S2.Se bloqueio ≠ NENHUM → parar e reportar (não adivinha).
- S3.Revalidar o DoR — se
algum item estiver aberto, marca
BLOCKED:e devolve ao Backlog. - S4.Executar 1–2 passos
da WU (pacing). Rodar
./scripts/gate.ps1. - S5.Gate verde → commit na feature branch; se WU fechou: PR auto-merge + tag.
- S6.Atualizar
PROGRESS.md+ lições. Parar num checkpoint seguro.
src/socialselling/, tests/, fixtures — tudo que muda o comportamento do
produto.
✅ Definition of Ready (DoR)
Card pode ir de Backlog → Todo?
- ① Objetivo observável em 1 frase (porquê + resultado verificável)
- ② Fatiada em 1 WU — cabe numa janela de execução
- ③ Contrato Pydantic definido; ADR vinculada se cruza módulo
- ④ Gherkin: caminho feliz + modo degradado + Open-World
- ⑤ Fixtures identificadas; sem bloqueio de rede paga/entitlement
- ⑥ Sem decisão de fronteira em aberto
- ⑦ Dentro do escopo canônico (§3/§5/ADR-000)
- ⑧ Determinismo viável (APIs mockadas, tolerância 1e-9)
- ⑨ DoD específico declarado no corpo da card
🏁 Definition of Done (DoD)
Card pode ir de In Progress → Done?
- ① Cenários BDD verdes e byte-idênticos (zero flakiness)
- ② Fixtures commitadas; testes não tocam rede
- ③ Gate completo:
ruff+mypy --strict+pytest✅ - ④ Invariantes semânticas respeitadas; persistência atômica
- ⑤ Escopo preservado — implementado o mínimo da fatia
- ⑥ PR com CI verde (
gh pr merge --squash --auto) - ⑦
PROGRESS.md+ lições atualizados no mesmo PR - ⑧ Card em Done + tag
vX.Y.Zse fechou um marco - ⑨ Fail-closed: gate vermelho após 2 tentativas →
BLOCKED:
⛔ Guardrails de autonomia (inegociáveis)
- Nunca commit/push direto na
main— só via PR com CI verde - Nunca
--force; rollback só viagit revertem PR - Nunca inventar especificação — ambiguidade →
BLOCKED:e para - Sem fixtures gravadas → não implementa módulos que tocam rede (M1/M2)
- Parar sempre num checkpoint seguro; nunca terminar no meio de passo destrutivo
🔓 Exceções ao modo noturno
- Pedido explícito do dono: "faça agora", "implemente isto" — o override sempre vence.
- Hotfix crítico:
mainquebrada ou bug crítico — corrigir na hora via PR + gate verde, registrar depois.
Fora desses dois casos, implementação de produto = card/noite.
Âncora de estado & cadência
📌 .ai/state/PROGRESS.md
Fonte da verdade do "onde paramos". O run lê no início e atualiza no fim. Contém: marco atual, tag verde, WU em andamento, passo (S1–S6), branch, próxima ação, bloqueios e histórico de runs.
Estado nunca vive na sessão — vive no git + PROGRESS.md. Qualquer run novo reconstrói o contexto lendo esses dois.
📅 Cadência recomendada
| Janela | Madrugada BRT (~02:00) — sem contenção com uso interativo |
| Frequência | 1 run/noite no início; ajustar pelo consumo semanal |
| Escopo/run | 1–2 passos de uma WU (cabe na janela; termina em checkpoint) |
| Supervisão | WUs com rede (M1/M2): gravar fixtures com o dono presente; WUs puras: mais seguras p/ rodar sós |
| Revisão | Dono revisa merges/tags da noite pela manhã; CI é a rede de segurança |
Documentos de referência desta camada
modo-operacional.md
Regra padrão dia/noite, fronteira card, fluxo de autoria, auto-learning evolutivo.
dor-dod.md
Portões de qualidade por coluna do board + template completo de card (DoR checklist).
autonomous-ops.md
Protocolo S1–S6 do run autônomo, guardrails, cadência, prompt do agente agendado e recuperação de falha.
execution-plan.md
Plano-mestre de WUs: validação, versão e rollback por passo.
devops-sre-iac.md
Práticas DevOps/SRE: CI, gate, versionamento e IaC do PoC.
versioning-strategy.md
Tags = pontos de restauração. Rollback público via revert, nunca reset/force.
Referência técnica
11 Contratos & modelo de dados
Todo o pipeline opera sobre contratos Pydantic v2 declarados
em src/socialselling/contracts.py — único ponto de verdade dos
modelos de dados. Cada módulo M1–M5 produz e consome tipos bem definidos; jamais compartilham
referências mutáveis entre camadas.
Fluxo de contratos pelo pipeline
Firmographics (indústrias, faixa de funcionários, geografias, modelos de negócio) · Technographics (tech mandatória/preferida/excluída) · PersonaMatrix (roles-alvo, senioridade mínima) · intent_triggers (sinais de hipótese)
evidence_id
(hash SHA-256 estável) · query, source_url, snippet, source_trust · missing_evidence: bool (Open-World explícito)
CompanyEntity
(nome, domínio, indústria, tecnologias, contatos, redes sociais) · PersonEntity (nome, cargo, senioridade) · derived_from: list[evidence_id] (rastreabilidade
obrigatória) · intent_signals, disqualifiers, persona · confidence
fit, intent, confidence, persona_fit, p_score, hard_filter_passed
positive_signals, negative_signals (lista de Driver com impact e texto) · missing_signals (Missing Evidence explícito) ·
degraded_mode
display_name,
company, role, sector,
location · links (Instagram first, LinkedIn, website) · contact (email, phone) · score (ProspectScore completo) · why_now[] (razões imediatas) · gaps[] (sinais ausentes) · sources[]
Fórmula de score (M3)
P = (w_fit · Fit + w_intent · Intent)
× Confiançaexp × persona_fit
w_fit = peso do
fit estrutural0.60w_intent = peso
de intenção0.40confidence_exponent0.5persona_fit
(fundadora)1.0persona_fit
(fundador)0.0M3 e M4 são funções puras: mesma entrada → saída
byte-idêntica (1e-9). Hard filter (disqualifier detectado) zera o lead. Pesos configuráveis
em runtime.toml e reajustáveis pelo feedback 👍/👎.
Catálogo de hipóteses (Intent)
Intent = Σ prior das hipóteses ativadas pelos intent_signals detectados pelo M2. Config em config/hypotheses_catalog.json.
Fundadora presa na operação — crescimento travado
Contratação sênior recente / formação de time
Expansão anunciada — nova unidade ou serviço
Intenção de adotar IA sem processo organizado
Conclusão recente de curso / mentoria de gestão
12 Estrutura do código-fonte
Cada subdiretório de src/socialselling/ tem uma responsabilidade estritamente
delimitada. Nenhum módulo importa de um módulo de nível acima no pipeline.
Todos os modelos Pydantic do pipeline (4 camadas): ICPCriteria → ObservedEvidence → Inference (+ CompanyEntity, PersonEntity) → ProspectScore / XAIPayload / RankedProspect → LeadCard. Regra: nenhuma lógica de negócio aqui.
modules/
m1_busca.py — queries Tavily/Apollo, cache atômico
24h, ObservedEvidence[]m2_extracao.py — lotes Gemini, parsing Pydantic,
Inference[]
m3_score.py — fórmula linear pura, hard filter,
ProspectScore[]
m4_ranking.py — sort estável por p_score, tie-break
por company_idm5_xai.py — gera XAIPayload por regras, sem IAskills/ — clientes externos
tavily_client.py — HTTP + cache + degradação
(429/timeout)gemini_client.py — geração JSON, backoff
exponencial, surfacia error.message cruapollo_client.py — REST Apollo, 3 endpoints, ledger
integradocore/ — infraestrutura interna
atomic.py — write-temp + os.replace (primitiva de escrita atômica)cache.py — cache frio em JSON, chave = hash SHA-256
do conteúdocredit_ledger.py — orçamento mensal Apollo (try_spend/refund)
request_ledger.py — orçamento diário RPD Gemini
apollo/ · corpus/ · learning/
apollo/schemas.py — contratos REST Apollo; normalize.py → ObservedEvidencecorpus/store.py — upsert idempotente por entity_id; waves.py — geração de queries por ondalearning/model.py — regressão logística pura; tuner.py — shrinkage + clamp; feedback_store.py — votos atômicosorchestrator.py
Pipeline unificado síncrono M1→M5. Injeta clientes,
cache e relógio; retorna list[LeadCard]. Exporta
run_pipeline() (CLI e web) e accumulate_and_rank() (corpus+ondas).
web/
app.py — rotas
FastAPI (run, feedback, pesos, status) · services.py — lógica de negócio da UI · static/ — cockpit HTML + JS · schemas.py — contratos da API web
config/
runtime.toml — todos os parâmetros ajustáveis
(pesos, TTLs, limites, opt-ins)hypotheses_catalog.json — hipóteses de intent com
priors e surface_signalsicp_criteria.*.json — ICPs concretos (talita,
example)scripts/
gate.ps1 / gate.sh — ruff + mypy + pytest em sequênciabootstrap.ps1 / bootstrap.sh — setup do zero (venv + deps + .env)
record_*_fixtures.py — gravam respostas reais de
Tavily/Gemini/Apollonew_card.ps1 — cria card no GitHub Project com
template DoRsetup_github_project.ps1 — sincroniza PROGRESS.md →
board13 Testes, BDD & observabilidade
A suíte de testes é a garantia de que o sistema é determinístico, byte-idêntico e jamais toca rede. Toda chamada externa é mockada com fixtures gravadas supervisionadas.
📄 Features Gherkin
tests/features/
m1_busca.feature · M2 · M3 · M4 · M5pipeline_smoke.feature — E2E byte-idênticoobjetivo_ranking.feature — objetivo de negócio
Cada módulo exige 3 cenários: feliz (caminho normal) + degradado (429/timeout → degrada, não quebra) + Open-World (sinal ausente → incerteza ↑, nunca falso).
🗂️ Fixtures gravadas
tests/fixtures/
Respostas reais de API capturadas uma vez, com supervisão, via scripts dedicados:
record_tavily_fixtures.pyrecord_gemini_fixtures.pyrecord_apollo_fixtures.py (requer plano pago)Depois de gravadas, os testes as usam via FakeTavilyClient / FakeGeminiClient — rede nunca é tocada em CI.
🔬 Garantias dos testes
- Reexecução byte-idêntica (smoke executa 2×)
- Tolerância numérica
abs(a-b) ≤ 1e-9 - IDs por hash SHA-256 estável (nunca UUID aleatório)
- Relógio injetado como parâmetro (
now: datetime) - Flakiness = falha (zero tolerância)
mypy --strictsem errosStrEnum(nãostr, Enum) para Python 3.11+
Observabilidade & SLOs do PoC
📊 logs/cognitive_trace.jsonl
Log append-only com um evento por decisão relevante do
pipeline. Cada linha: {ts, module, action, lead_id, inputs_hash, outputs_hash, tokens, degraded}.
Permite auditar custo, reproduzir decisões e, no futuro, medir latência sem
instrumentação extra. Rastreabilidade: Evidence → Inference → Score → Decision garantida via
derived_from.
🎯 SLOs do PoC
| SLI | Alvo (SLO) |
|---|---|
| Testes verdes na main | 100% (bloqueante) |
| Determinismo pipeline | 100% byte-idêntico (bloqueante) |
| Cobertura de tipos | mypy --strict sem erros |
| Custo por execução | ≤ orçamento runtime.toml |
| Latência (N≤50 leads) | p95 a calibrar via trace |
Error budget zero para determinismo e testes. Latência/custo: alvo a calibrar — não bloqueia merge no PoC.
14
Configuração central (runtime.toml)
config/runtime.toml é o painel de controle do PoC. Nenhum
segredo aqui (chaves de API ficam no .env). Todas as features
opt-in são desligadas por padrão para preservar a paridade do smoke E2E.
[scoring] — fórmula do score
w_fit = peso fit estrutural0.60w_intent = peso de intenção0.40confidence_exponent0.5w_fit_tech / w_fit_industry0.60 / 0.40intent_evidence_norm5[persona] — multiplicadores por tipo
fundadora1.0
← alvoindefinido0.5empresa0.35fundador0.0 ←
hard filter[finops] — controle de custo
tau_finops —
limiar de poda0.60kappa_degraded —
penalidade em modo degradado0.80[gemini] — cognição
modelgemini-2.5-flash-litebatch_size50timeout_seconds120rpd_enabledfalse ← opt-inrpd_cap
req/dia1000[cache] · [tavily] · [runtime]
cache.ttl_hours24htavily.max_queries3tavily.persona_term"fundadora"runtime.max_leads_per_cycle50[apollo] — sensor firmográfico (opt-in)
enabledfalse ←
opt-inreveal_top_n20org_enrich_ttl_hours720h (30d)reveal_ttl_hours2160h (90d)caps.data_credits_cap100/mês[corpus] & [learning] — opt-ins ativos
corpus.enabledtrue ← ligadocorpus.pathdata/corpus/leads_corpus.jsoncorpus.waves_pathdata/corpus/waves.jsonlearning.enabledtrue ← ligadolearning.min_likes / min_dislikes3
/ 3learning.l20.1learning.epochs500learning.shrinkage_max0.5enabled = false deixa o pipeline byte-idêntico ao baseline. Ligar
uma feature = alterar o caminho quente; desligar = zero impacto. O smoke E2E valida isso a cada PR.
Em síntese
O que é o SocialSelling
O SocialSelling torna a busca de clientes mais eficiente e automática com IA, construído com engenharia de verdade: decisões registradas em ADRs/SDDs, um SDD-to-Code Loop com gates determinísticos e aprendizado contínuo por feedback.
- Prospecção automática com IA — encontra e qualifica clientes com menos esforço manual.
- ADRs/SDDs — arquitetura e comportamento documentados como fonte da verdade.
- SDD-to-Code Loop + gates — determinismo e Open-World no caminho crítico.
- Aprendizado por feedback — o sistema melhora com o resultado real.
Perguntas frequentes
Perguntas frequentes
O que é o projeto SocialSelling?
É um sistema que torna a busca e a qualificação de clientes mais eficientes e automáticas com IA. Foi construído com engenharia disciplinada: decisões em ADRs/SDDs, um loop SDD-to-Code com gates determinísticos e aprendizado por feedback.
Como o determinismo e o Open-World aparecem aqui?
O caminho crítico resolve o que dá para resolver com regras (determinístico-primeiro) e trata ausência de dado como incerteza explícita (Open-World), não como "falso". Isso evita que a IA invente qualificações e mantém o resultado auditável.
O que é o SDD-to-Code Loop?
É o ciclo em que a especificação dirige a implementação e os gates validam cada passo antes de avançar: escreve-se a intenção, a IA implementa contra ela e os testes/gates provam a conformidade. O aprendizado por feedback realimenta a spec.