SymbolicAI: uma perspectiva neuro-simbólica sobre LLMs

• SymbolicAI é um framework de programação neuro-simbólica que combina Python e LLMs de forma natural
• Por meio da unidade básica Symbol, oferece suporte tanto a manipulações sintáticas quanto semânticas
• O recurso de Contracts aplica validação de dados e lógica de correção automática às previsões do LLM, garantindo confiabilidade e robustez
• Permite integração com diversos motores externos (OpenAI, Anthropic, huggingface etc.), além de busca na web, geração de imagens e processamento de voz
• Destaca-se por um sistema de gerenciamento de configuração baseado em prioridade e por fortes recursos de customização

---

SymbolicAI: visão geral do projeto e sua importância

• SymbolicAI é uma biblioteca neuro-simbólica (Neuro-Symbolic) que oferece suporte natural à combinação entre programação Python clássica e LLMs programáveis e diferenciados (grandes modelos de linguagem)
• Graças ao seu design modular, é fácil expandir, trocar motores e integrar ferramentas
• Integra-se com várias ferramentas, como motores locais, busca na web e geração de imagens, sendo adequada tanto para uso experimental quanto prático

Introdução aos principais conceitos

Primitives

• Primitives são as unidades básicas de construção, e o núcleo é o objeto Symbol

• O objeto Symbol oferece suporte aos modos sintático (syntactic) e semântico (semantic)

  • Sintático (syntactic): funciona como um valor Python comum, implementando operações seguras e rápidas, como comparações e cálculos
  • Semântico (semantic): conecta-se ao motor neuro-simbólico para compreender significado e contexto, permitindo comparações e manipulações semânticas flexíveis

• O modo sintático é o padrão, e a execução semântica só é ativada quando a operação do motor é necessária

Como alternar entre os modos semântico/sintático

• Definir a opção semantic=True na criação
• Alternar livremente com as propriedades .sem (semantic) e .syn (syntactic)
• Conversão automática para o modo semântico ao chamar funções semânticas (como map)

Exemplos de operações

• ==: no modo sintático faz comparação literal; no semântico, equivalência semântica (ex.: 'Hi' == 'Hello' resulta em True)
• +, &, .startswith(), .choice(), .foreach(), .cluster(), .similarity() etc.
• Permite manipulações semânticas complexas e encadeamento lógico

Contracts

• Adota o princípio de Design by Contract para compensar a incerteza dos LLMs
• Modelos de dados e regras de validação podem ser definidos com decorators
• Oferece vários recursos de estabilidade, como correção automática de erros, novas tentativas e acúmulo de histórico para entradas/saídas inválidas
• Compatibilidade embutida com modelos de dados do Pydantic, validação de campos, geração automática de prompts e tratamento de erros

Principais características do recurso de Contract

• pre_remedy/post_remedy: correção automática de erros de entrada/saída
• accumulate_errors: insere o histórico de erros
• remedy_retry_params: define parâmetros de controle de nova tentativa (número de tentativas, atraso, backoff etc.)

Exemplos detalhados e explicações adicionais podem ser consultados na documentação oficial e na página do DeepWiki

Motores externos e extensibilidade funcional

• Atualmente oferece suporte a vários motores neuro-simbólicos, como OpenAI e Anthropic (API/local)
• Também é possível executar motores próprios localmente, como {huggingface, llama.cpp}
• Permite integrar motores adicionais para voz, imagem, busca na web etc. (exige instalação de pacotes de dependência separados)
• Fornece de forma integrada recursos práticos de ML/AI, como busca, clustering, OCR e indexação

Sistema de gerenciamento de configuração (Configuration)

Gerenciamento de arquivos de configuração baseado em prioridade

• Modo de depuração (pasta do projeto): para desenvolvimento e testes

• Configuração por ambiente Python ({python_env}/.symai/)

• Configuração global (~/.symai/): para padrão/backup

• Os itens de maior prioridade entre esses três locais são aplicados automaticamente

Principais arquivos de configuração

• symai.config.json: gerencia as principais opções do SymbolicAI
• symsh.config.json, symserver.config.json: configurações para shell e servidor

Exemplos de arquivos de configuração

• Definição explícita de API Key, nome do modelo, tipo de motor etc.
• A opção SUPPORT_COMMUNITY permite consentir com a coleta de dados (para pesquisa e melhoria de qualidade)
• O controle de avisos ao usuário pode ser ativado/desativado pela variável de ambiente SYMAI_WARNINGS

Configuração do ambiente e testes

• São necessários pacotes externos como ffmpeg (voz) e chromedriver (crawler web)
• A execução de testes usa pytest, com suporte à verificação de cobertura

Materiais de referência e guia de uso

• O DeepWiki e o GitBook oficial oferecem farto material de referência e tutoriais em vídeo
• Um artigo publicado no Arxiv explica a teoria e os detalhes do framework
• Licenciado sob BSD-3-Clause

Conclusão

• O SymbolicAI combina a clareza dos sistemas simbólicos com a flexibilidade das redes neurais, sendo um framework muito adequado para serviços focados em confiabilidade baseados em LLM e para pesquisa experimental
• Com um design voltado para configuração, extensibilidade e confiabilidade, oferece várias possibilidades de aplicação para startups e profissionais de TI

Suporte a desenvolvedores e comunidade

• Recursos de contribuição, contatos e canais de suporte (e-mail, website, Discord) são divulgados ativamente

[GN⁺]

Comentários do Hacker News

• Esse tipo de magia voodoo é realmente fascinante.
  Um exemplo que achei divertido foi usar map lambda semântico,
  por exemplo, quando há uma lista de símbolos S, ao chamar S.map('converter todas as frutas em vegetais'), apenas as frutas viram vegetais e o resto permanece igual
  Também dá para comparar recebendo parâmetros conforme o contexto. Por exemplo, determinar se Hello, good morning! e Hi there, good day! têm o mesmo significado no contexto de saudação, ou comparar Good morning, sir. e Hey, what’s up? pelo nível de formalidade
  Também é possível fazer combinações lógicas semanticamente, como operadores de bits. Dá para combinar regras e observações com &, como em bullets, para chegar a uma conclusão
  A função interpret() parece poderosa
  Fiquei curioso para saber o que inspirou o OP neste projeto, em quais áreas ele aplicou isso na prática e qual é seu caso de uso favorito

  • Recomendo o Lotus, uma biblioteca de dataframe em Python
    Dá para expandir semanticamente todos os operadores relacionais centrais de forma bem simples
    Cada chamada vira um ponto de “modelo”, o que também facilita expandir depois para o lado de machine learning
    Parece que SQL em nuvem, como o Snowflake, está indo cada vez mais nessa direção
    Implementei um sistema parecido no louie.ai. Ele permite lidar com dados de forma conversacional por meio de AI notebook, dashboard e API (Splunk, Databricks, graph DB etc.) e identifica automaticamente operadores simbólicos + semânticos com base no contexto
    Isso ajuda muito no trabalho real
    Meus principais casos de uso são:
    com semantic map, buscar alertas em índices do Splunk, adicionar flags aos suspeitos e incluir uma descrição,
    e depois resumir isso com semantic reduce para até gerar um relatório em linguagem natural

  • Pergunta sobre por que a cenoura seria o resultado da transformação de maçã em vegetal

  • A resposta ficaria bem longa
    O projeto começou no fim de 2022, mas recentemente os modelos melhoraram; as partes fundamentais já existiam desde a época do GPT-3
    O DbC (Design by Contract) que apareceu recentemente é realmente muito único
    Resolveu todos os problemas que eu tinha com agentes. Em especial, ao encadear vários contracts, os guardrails se propagam naturalmente, o que é bastante eficaz
    Implementei praticamente todas as ferramentas customizadas por conta própria
    Por exemplo, a busca web da OpenAI é boa, mas não é customizável o suficiente, então desenvolvi e uso meu próprio deep research agent
    Thread com um exemplo de resultado do primeiro dia
    Estou tocando uma empresa e também construí uma automação de geração de documentos end-to-end ligando 3 contracts
    Veja este PDF de demonstração
    O prompt de entrada pede
    “analisar padrões em arquivos, comparar de forma abrangente formatos diversos de prompt (XML, markdown etc.), tendência a bajulação, modo de uso de ferramentas, guardrails éticos, características arquiteturais e gerar um relatório”
    Apresentei os contracts nesta postagem de março de 2025, e desde então eles evoluíram bastante, mas a intenção básica e a motivação continuam as mesmas

• A ideia de poder usar operadores semânticos como == e + parece fertilizar ideias novas
  É uma empolgação parecida com a de quando conheci pela primeira vez a álgebra conceitual nos primórdios dos word embeddings, com coisas como King - Man + Woman = Queen
  Mas a integração entre redes neurais e símbolos (lógica) aqui, como na maioria dos sistemas, ainda é rasa ou separada
  Referência
  A verdadeira inovação deve vir quando houver uma integração muito mais fundamental no futuro
  Na nossa empresa (Onton) também estamos pesquisando nessa direção
  O objetivo é 1) uma representação totalmente integrada (nem simbólica nem deep learning), 2) aprendizado contínuo mesmo com poucos dados ruidosos (sem esquecimento), 3) 100% de confiabilidade em operações matemáticas/simbólicas, 4) zero alucinações (hallucination)
  No momento, colar vários sistemas com “cola quente” ainda é útil, mas uma arquitetura integrada deve virar o jogo

• Compartilhamento de links do notebook oficial de código com explicações e exemplos e do PDF do artigo oficial

• Relato de erro no código (valid_sizes não está definido em “correctness contracts”)

  • Obrigado pelo feedback. Era um resquício que sobrou do processo de refatoração. Já corrigi

• Obrigado a todos que deram opiniões sobre este tema e ofereceram apoio
  Eu não esperava esse tipo de reação e estou sempre disponível para conversar por e-mail/Twitter
  Foi realmente ótimo falar com vocês

• Há algo frustrante aqui
  O próprio termo “Symbolic AI” já tem uma definição estabelecida

  • Já ouvi bastante essa opinião
    Talvez eu mude o nome em breve
    Também coloquei uma nota de rodapé no artigo explicando o motivo da nomeação, e dei esse nome ao projeto em homenagem a Newell e Simon, que lideraram a pesquisa fundamental

• Tenho uma dúvida
  Como funciona a política de custos
  A estrutura é tal que toda vez que se executa uma linha contendo operações em linguagem natural (ainda mais se usar API externa) o custo de inferência do LLM continua sendo cobrado?
  Por exemplo, isso também acontece se uma função “simbólica” for chamada repetidamente dentro de um loop?

  • Sim
    Por exemplo, ao usar a API da OpenAI, cada operação semântica gera uma chamada à OpenAI e portanto um custo
    Se você hospedar diretamente um LLM local com llama.cpp etc., aí só há o custo de hospedagem, sem custo separado de inferência

  • Com certeza vai precisar de algo como cache

• Eu não esperava, mas de repente isso ficou muito popular, então estou meio surpreso
  Era para eu estar dormindo, mas estou usando minha experiência atual de privação de sono para continuar participando da conversa

• Como em programação funcional (FP), todo Symbol se comporta como um valor puro
  As operações se compõem em um fluxo limpo e rastreável
  O modelo intervém nas etapas ambíguas
  Como operações de IO em FP, chamadas a modelos generativos são tratadas como efeitos colaterais delimitados por escopo
  Normalmente o grafo de raciocínio é determinístico, e só delega ao modelo quando necessário
  A demo é realmente impressionante

  • Quase isso
    Desde o começo foi projetado de forma funcional
    Mesmo em baixo nível, tudo segue princípios funcionais, e internamente também se chama functional.py ou core.py
    Decorators também são usados por toda parte, o que ajuda bastante em refatoração, expansão e gerenciamento de bugs

• Hoje em dia os LLMs até geram todo o código,
  então fico curioso sobre que vantagem uma estrutura que carrega contexto como Symbol e pode ser manipulada facilmente com operadores de Python oferece
  em comparação com escrever código manualmente, verificando tudo passo a passo
  Por exemplo, até daria para fazer essa transformação semântica escrevendo diretamente a sintaxe desse jeito, mas não seria possível simplesmente pedir a um LLM um programa que converta uma lista de frutas em vegetais?
  Não seria isso suficiente?
  Quero entender qual é a diferença essencial

  • Eu diria que isso ajuda a prevenir alucinações (hallucination)
    Quando você faz o LLM gerar um sistema formal, a verificação é muito mais fácil do que em um sistema de uso geral