Baobáxia

Rede de saberes descentralizada, offline-first e federada da Rede Mocambos.

Cada comunidade roda sua própria instância (uma mucua), dona dos seus dados, que funciona sem internet e sincroniza com outras quando há rede — inclusive por pendrive. A documentação de arquitetura está em docs/baobaxia-desenho-completo.md.

Conceitos

• Saber — a unidade de conhecimento. Tudo é um saber, com um campo nature (midia, artigo, colecao, mocambola, galaxia, mucua, territorio…).
• Mucua — a instância/nó de uma comunidade. Uma por instalação.
• Galáxia — um acervo (coleção temática/territorial de saberes).
• Mocambola — a pessoa, com identidade criptográfica válida em toda a rede.

O sistema de arquivos é a fonte da verdade: cada saber é um saber.bbx (YAML legível + markdown) versionado com git; binários por git-annex. O índice SQLite (busca full-text) é um cache reconstruível.

Instalação

pip install -r requirements.txt
pip install -e .

Requer Python 3.10+. Para sincronização e mídia, instale no sistema: git-annex (ou DataLad), ffmpeg (vídeo) e poppler-utils (PDF).

Uso rápido

# criar uma galáxia (gera a mucua e o admin)
bbx criar-galaxia "Meu Acervo"

# subir a API (lê variáveis de um arquivo .env, se houver)
bbx api

# autenticar UMA vez (sessão persistente; não repete usuário/senha depois)
bbx login --usuario ana

# escolher a galáxia ativa (usada por padrão ao publicar)
bbx galaxias                            # lista (★ = ativa)
bbx galaxia "Meu Acervo"                # fixa a ativa (nome/prefixo/uuid)

# consultar (aceita uuid, prefixo de 8 chars ou slug em ver/editar/deletar)
bbx buscar "pesca artesanal"
bbx buscar pesca --tipo video          # faceta por tipo de conteúdo
bbx listar --nature artigo             # por nature
bbx ver ab12cd34                        # 8 chars bastam
bbx editar ab12cd34 titulo "Novo título"
bbx buscar pesca --json                  # saída JSON p/ scripts

# publicar — forma DIRETA
bbx publicar foto.jpg video.mp4 --titulo "Pescaria"
bbx publicar foto.jpg --titulo -        # infere o título do nome do arquivo

# publicar — forma EM ESTÁGIOS (interativa, pergunta título + metadados)
bbx publicar midia                       # (ou: bbx publicar artigo)
bbx add foto.jpg video.mp4               # anexa ao rascunho (repita à vontade)
bbx enviar                               # cria o saber de verdade
bbx rascunho / bbx cancelar              # ver / descartar o rascunho

A CLI e o bot XMPP usam a mesma camada de operações (publica/operacoes.py), então buscar/publicar/editar/deletar se comportam igual nos dois — sem código duplicado. Todos os comandos rodam in-process (rápido) ou autônomos contra uma mucua remota via --api-url.

A API REST sobe em http://127.0.0.1:8000 com documentação interativa em /docs. São mais de 100 endpoints cobrindo saberes, coleções, relações, estrutura, autenticação, sincronização, recuperação e federação.

Recursos

Núcleo

• Modelo unificado Saber (uma entidade, muitas naturezas); saber.bbx legível.
• FS como fonte da verdade; índice SQLite (FTS5) reconstruível com bbx reindex.
• Busca full-text robusta (lida com hífen, aspas e caracteres especiais).
• Mídias variadas (foto + vídeo + áudio + PDF) convivem no mesmo saber.
• Cópia entre galáxias (com proveniência), mover com verificação de integridade.
• Coleções cross-galáxia (formatos lista, história e livro), relações entre saberes, multilíngua.
• Galáxia inteira num .zip (história git + anexos): bbx exportar-galaxia / bbx importar-galaxia, ou pelo site.

Identidade e segurança (modular, via BBX_AUTH_MODE)

• Identidade criptográfica Ed25519/X25519; chaves privadas nunca viajam.
• Login federado entre mucuas; autoria assinada e verificável.
• Proteção por saber: público, restrito (ACL) ou cifrado de ponta a ponta.
• Recuperação de identidade por guardião, frase-semente ou chave na mucua-natal.

Federação (modular, via BBX_FED_*) — só conteúdo público federa

• Transparente: publicar um saber público já o federa; saberes que chegam de fora entram no acervo e na busca normais.
• XMPP — feeds seguíveis + bot conversacional (publique e busque pelo chat).
• ActivityPub — interopera com o Fediverso (atores, outbox/inbox, WebFinger).
• OAI-PMH / ResourceSync — colheita do acervo público em Dublin Core.

Ferramentas

• API REST — interface programática completa.
• CLI bbx — buscar, publicar, listar, ver. Roda dentro da mucua (in-process, rápido) ou autônomo via --api-url contra uma mucua remota.
• Bot XMPP (bbx xmpp-bot) — interface conversacional pelo cliente de chat.

A publicação detecta o que foi enviado (texto → artigo, arquivo → mídia), normaliza vídeo, baixa do YouTube, publica de URLs, evita duplicatas por hash, e aceita metadados Dublin Core (idioma, direitos, autoria, localização…).

Configuração

Todas as opções são variáveis de ambiente. O bbx api carrega um arquivo .env automaticamente. São muitas, mas quase todas são ajuste fino com padrão bom — a referência completa, por tema e com padrões, marcando o que é essencial, comum e ajuste fino, está em docs/baobaxia-configuracao.md. Essenciais:

BBX_SECRET_KEY=<segredo forte>     # gere: python3 -c "import secrets;print(secrets.token_urlsafe(48))"
BBX_MUCUA_PUBLIC_URI=https://...   # URL pública desta mucua (monta links permanentes)
BBX_CADASTRO_ABERTO=on             # visitantes criam conta (padrão off)
BBX_AUTH_MODE=ambos                # senha | chave | ambos
# opcionais mais comuns
BBX_FED_XMPP=on                    # XMPP
BBX_FED_AP=on                      # ActivityPub (+ BBX_AP_BASE_URL)
BBX_CANAIS=on                      # rádio/TV: on | manual (só ao vivo) | off
BBX_ENRIQUECER=ocr,transcricao     # OCR e legendas (ver docs/baobaxia-enriquecimento.md)

Estrutura

baobaxia/
  core/         Saber, repositório, índice (FTS5), relações
  natures/      schemas por nature
  services/     autoria, ACL, recuperação, cópias, pedidos, permissões
  infra/        storage (.bbx), git/annex (sankofa), identidade, cifragem
  applications/ lentes: acervo, blog, timeline, mapa
  federacao/    visibilidade, adaptadores (XMPP, ActivityPub), bot, ingestão
  publica/      operações compartilhadas, processamento, backend HTTP
  api/v3/       API REST (FastAPI)
  cli.py        linha de comando (bbx)

Documentação

• docs/baobaxia-desenho-completo.md — arquitetura do sistema (documento principal)
• docs/baobaxia-configuracao.md — todas as variáveis de ambiente
• docs/baobaxia-xmpp-guia.md — montar servidor XMPP (Prosody/ejabberd)
• docs/baobaxia-enriquecimento.md — OCR, texto de anexos e legendas (Whisper)
• os livros "Raízes do Baobáxia" (curso do código) e "Frutos do Baobáxia" (guia de uso) ficam fora deste repositório, como conteúdo de galáxia

Licença

Software livre da Rede Mocambos.