csc-cia-stne 0.1.72

Biblioteca do time CSC-CIA utilizada no desenvolvimento de RPAs

csc-cia-stne

Biblioteca interna desenvolvida e mantida pelo time CSC-CIA da Stone, voltada ao desenvolvimento de RPAs e rotinas automatizadas.

Reúne integrações com sistemas internos e externos (Stone Admin, ServiceNow, Waccess, BC Correios, BC STA, GCP, Slack, e-mail, FTP/SFTP, Provio, Jerry/IA) e utilitários comuns para bots (logging, segredos, datetime, base64, PDF, configuração por ambiente, etc.).

O objetivo é não precisar reimplementar, em cada novo robô, funcionalidades que já são usadas com frequência pelo time.

---

Sumário

• Instalação
• Recursos / Módulos
• Quickstart
• Variáveis de ambiente
• Convenções importantes
• Documentação
• Suporte

---

Instalação

Em projetos novos, recomendamos o uso do uv:

uv init meu-projeto
uv add csc-cia-stne

Para adicionar a uma rotina já existente:

uv add csc-cia-stne

Também é possível instalar via pip:

pip install csc-cia-stne

Python suportado: 3.10+ (recomendado 3.11 ou superior).

---

Recursos / Módulos

A lib é organizada em módulos por integração/funcionalidade. Os principais são:

Integrações Stone / internas

Módulo	Descrição
stne_admin	Integração com o Stone Admin
servicenow	Listagem de tickets, anexos e operações no ServiceNow
karavela	Helpers para execução em ambiente Karavela (secrets, health-check)
wacess	Integração com o sistema Waccess
provio	Integração com o Provio
jerry	Cliente da API Jerry (IA / OCR / chat completions Stone)

Banco Central / órgãos externos

Módulo	Descrição
bc_correios	Automação do BC Correios
bc_sta	Automação do BC STA (Sistema de Transferência de Arquivos)

Google Cloud

Módulo	Descrição
gcp_bigquery	Consultas, inserções e utilitários para BigQuery
gcp_bucket	Upload/download de arquivos em buckets GCS
gcp_document_ai	OCR e extração via Google Document AI
google_drive	Upload/download e organização de arquivos no Google Drive

Comunicação e arquivos

Módulo	Descrição
slack	Envio de mensagens, anexos e blocos para o Slack
email	Envio e leitura de e-mails (SMTP/IMAP)
ftp	Cliente FTP/SFTP
web	Automação web (Selenium / BotCity)

Logging

Módulo	Descrição
logger_rich	Logger formatado com Rich para execução local/console
logger_json	Logger em formato JSON, usado automaticamente no ambiente Karavela

Utilitários (csc_cia_stne.utilitarios)

• get_secret — resolução de segredos com fallback (env → ./secrets/ → ./.secrets/ → /secrets/ → BotMaestro)
• get_config — leitura de settings.yaml por ambiente (dev/qa/prod)
• titulo — header padronizado do robô (printa local / loga em Karavela)
• b64encode / b64decode — utilidades base64
• extrair_x_paginas_pdf_from_base64 — extração e recorte de páginas de PDF
• Conversores datetime, validação de JSON, recriação de pastas, conversores de retorno BigQuery, entre outros.

---

Quickstart

Setup mínimo de uma rotina

from csc_cia_stne import logger
from csc_cia_stne.utilitarios import titulo

log = logger(__name__)

titulo(
    project_name="Minha rotina",
    project_version="0.1.0",
    project_dev_name="Roberto Lins",
    project_dev_mail="[e-mail]",
)

log.info("rotina iniciada")

Lendo um segredo com fallback automático

from csc_cia_stne.utilitarios import get_secret

# Resolve, nesta ordem: env var → ./secrets/MINHA_SECRET → ./.secrets/... → /secrets/... → BotMaestro
senha = get_secret(name="MINHA_SECRET")

if senha is None:
    raise RuntimeError("Segredo MINHA_SECRET não encontrado")

Consultando tickets no ServiceNow

from csc_cia_stne import ServiceNow
from csc_cia_stne.utilitarios import get_secret

svc = ServiceNow(
    username=get_secret(name="SERVICENOW_USERNAME"),
    password=get_secret(name="SERVICENOW_PASSWORD"),
    env="qa",
)

resultado = svc.listar_tickets(
    tabela="x_stps2_services_catalog_base_task",
    campos=["number", "sys_id", "state"],
    query="assignment_group=45251cd61bed42544867a68fe54bcbe3",
    limite=50,
)

for ticket in resultado["content"]["result"]:
    print(ticket["number"]["display_value"])

Karavela: secrets e health-check

from csc_cia_stne import Karavela

k = Karavela()
token = k.get_secret(name="MEU_TOKEN")

k.create_health_check_file(health_check_filename="./healthy_check/healthy")
# ... execução do robô ...
k.destroy_health_check_file()

---

Variáveis de ambiente

Variável	Descrição
ambiente_de_execucao	Quando definida como karavela, o logger passa para o formato JSON e o helper titulo passa a logar (em vez de printar).
log_level	Nível mínimo do logger (DEBUG, INFO, WARNING, ERROR, CRITICAL).

Demais variáveis específicas (credenciais, URLs, etc.) são consumidas por cada módulo conforme necessidade — consulte a documentação interna.

---

Convenções importantes

Antes de usar a lib em produção, é importante conhecer alguns padrões:

• Envelope de retorno: a maioria dos métodos retorna dict no formato {success/status, data/result, error}. Em geral, não levantam exceção nas operações de negócio — sempre cheque o status do dict.
• .env no cwd: várias classes carregam um .env do diretório atual via python-dotenv no __init__. Em jobs que rodam fora do diretório do projeto, garanta que o .env seja resolvido de outra forma.
• Conexões silenciosas: alguns construtores não levantam exceção quando a conexão falha. Cheque atributos como is_connected e error antes de usar.
• Logger é factory: from csc_cia_stne import logger devolve uma função. Use log = logger("meu_modulo"). O formato (Rich x JSON) é decidido automaticamente pelo ambiente.
• Detecção de ambiente Karavela: definindo ambiente_de_execucao=karavela, o logger e o titulo mudam para o modo container/JSON sem alteração de código.

---

Documentação

A documentação completa, com exemplos por classe e receitas (padrões maduros usados em produção: logger console+arquivo, agente Jerry+LangChain com saída Pydantic, OCR + classificação por IA, pipeline GCS → Google Drive, etc.), está no repositório interno:

GitHub — stone-payments/cia-libs (acesso restrito)

---

Suporte

• Time mantenedor: CSC-CIA / Stone
• Contato: [e-mail]
• Licença: MIT