Nullain Agent

Pensa. Planeja. Executa.
Sua assistente de IA que não só conversa — ela age.

Português (Brasil) • English

---

O que é a Nullain?

A Nullain Agent é uma assistente inteligente com personalidade própria:
ela entende o que você precisa, organiza o caminho e coloca a mão na massa.

Não é só mais um chat.
É um espaço onde ideias viram ações — com clareza, ritmo e controle.

Nullain Agent · Pensa, planeja e executa ☠️☕

Como ela funciona

  você fala  →  ela entende  →  planeja o passo a passo  →  executa  →  responde

1. Escuta	2. Organiza	3. Age
Você pede em linguagem natural	Ela monta o plano sem enrolação	Conecta com o que você usa no dia a dia

Respostas em tempo real (texto que aparece enquanto ela pensa).
Sem parede de texto: ideias em listas, tabelas e blocos claros.

O que ela entrega

Conversa que flui Chat limpo, escuro e moderno. Histórico, nova conversa, interface que você já reconhece.	Resposta ao vivo O texto nasce na hora. Você acompanha o raciocínio sem esperar a página “travar”.
Conectada ao seu mundo Ela se liga às ferramentas que você já usa (repos, dados, infraestrutura…) e age com segurança.	No seu controle Você define o que está ligado. Ações sensíveis pedem confirmação. Nada de caixa-preta.

Experiência

Momento	O que você sente
Abre	Tela limpa, identidade forte, zero ruído
Pede	Uma frase basta — sem formulários eternos
Acompanha	Status claros: pensando · conectando · escrevendo
Recebe	Resposta estruturada, útil, pronta para usar

Para quem é

• Quem quer um assistente de verdade, não só um gerador de texto
• Quem vive entre várias ferramentas e quer um ponto único de comando
• Quem valoriza design escuro, minimal e profissional
• Quem prefere open-source e dono da própria stack

Princípios da Nullain

  clareza  >  volume
  ação     >  teoria
  controle >  automação cega
  estilo   >  template genérico

---

🏗️ Arquitetura

A Nullain não implementa o próprio loop de agente. Ela é um produto construído sobre o Nullain Agent SDK (nullain-sdk no PyPI), consumido como dependência comum — o SDK cuida do raciocínio, ferramentas, permissões, memória e persistência; este repositório cuida do produto: interface, autenticação, integrações de domínio e deploy.

flowchart TB
    subgraph PROD["🖥️ Nullain Agent — este repositório"]
        direction LR
        UI(["Web UI<br/>SSE streaming"]) --> API(["FastAPI<br/>web/server.py"]) --> Bridge(["AgentBridge<br/>agent/bridge.py"])
    end

    subgraph SDKL["⚙️ Nullain Agent SDK — nullain-sdk"]
        direction LR
        Agent(["Agent"]) --> Loop(["Plan · Act · Verify"]) --> Perm(["PermissionPolicy"]) --> Tools(["ToolRegistry"])
    end

    subgraph DOMAIN["🧰 Ferramentas de domínio — este repositório"]
        direction LR
        Pay(["ZuckPay<br/>PIX · SPEI"]) --- Img(["Wavespeed<br/>imagem"]) --- Rag(["RAG<br/>Qdrant"]) --- Box(["Sandbox<br/>e2b · docker · aio"]) --- Mcp(["Composio MCP"])
    end

    subgraph STATE["💾 Estado"]
        direction LR
        PG(["PostgresEventStore<br/>ou SQLite"]) --- QD(["Qdrant<br/>por tenant"]) --- RD(["Redis<br/>cache · métricas"])
    end

    Bridge --> Agent
    Tools --> DOMAIN
    Agent --> PG
    Rag --> QD
    API --> RD

    classDef prod fill:#14b8a6,stroke:#0f766e,color:#fff
    classDef sdk fill:#6366f1,stroke:#4338ca,color:#fff
    classDef domain fill:#f59e0b,stroke:#b45309,color:#fff
    classDef state fill:#64748b,stroke:#334155,color:#fff
    class PROD prod
    class SDKL sdk
    class DOMAIN domain
    class STATE state

Loading

A divisão de responsabilidades

Camada	Quem resolve	Onde
Interface, autenticação, SSE	Este repositório	web/server.py, web/static/
Construção e cache do agente	Este repositório	agent/bridge.py
Loop Plan/Act/Verify, contexto, memória	SDK	nullain-sdk
Permissões e sandbox de SO	SDK	nullain-sdk
Ferramentas de arquivo, shell, git, web	SDK	nullain-tools
Pagamentos, imagem, RAG, sandbox remoto	Este repositório	agent/bridge_tools.py, agent/rag_tools.py

Como o SDK é estendido aqui

O AgentBridge (agent/bridge.py) constrói um Agent por (thread_id, usuário, modelo) e usa quatro pontos de extensão do SDK:

1. Identidade própria. Escreve SOUL.md e AGENTS.md no workspace do agente no boot. O PromptAssembler do SDK os lê e o SOUL.md substitui a identidade padrão (que é a de um agente de programação) pela de uma assistente de uso geral — junto com regras explícitas de escolha de ferramenta.
2. Ferramentas de domínio. Registra pagamentos, geração de imagem, RAG, sandbox e MCP no mesmo ToolRegistry das ferramentas embutidas, com PermissionLevel por ferramenta.
3. Permissão fail-closed. O permission_callback aprova automaticamente apenas write_file e bash — contidos no workspace isolado do agente. Qualquer outra ferramenta ASK (pagamentos, ações Composio) é negada até existir um fluxo real de confirmação humana.
4. Estado compartilhado. Com SUPABASE_DB_URL configurada, usa o PostgresEventStore do SDK — um único pool no processo, compartilhado por todos os agentes em cache, o que permite múltiplas réplicas lendo a mesma história de sessão. Sem ela, o SDK cai no SQLite local.

Stack

Runtime	Python 3.12 · FastAPI · uvicorn
Engine	nullain-sdk[rag,postgres]
Interface	HTML/CSS/JS sem framework, streaming por SSE
Eventos	Postgres/Supabase quando configurado, SQLite como padrão
Memória longa	Qdrant, uma coleção com isolamento por tenant_id
Sandbox	e2b · Docker local · AIO Sandbox (com browser e VNC ao vivo)
Cache/métricas	Redis (opcional)

Isolamento entre usuários

Três mecanismos, todos ancorados no e-mail do usuário autenticado:

• A chave de cache do agente inclui o usuário, então um thread_id reaproveitado nunca serve o ToolRegistry de outra pessoa
• As credenciais de pagamento são capturadas por closure na construção da ferramenta — o modelo não consegue informá-las como argumento
• A memória RAG é filtrada por tenant_id em toda escrita e busca

Configuração

Todas as variáveis vivem em .env.example. As principais:

# Modelo
LLM_PROVIDER=ollama                 # ollama · openai · xai
LLM_MODEL=glm-5.2:cloud
OLLAMA_API_KEY=...

# Estado
SUPABASE_DB_URL=...                 # vazio = SQLite local
QDRANT_URL=...                      # memória longa (opcional)
REDIS_URL=...                       # cache/métricas (opcional)

# Sandbox
SANDBOX_PROVIDER=aio                # e2b · docker · aio · vazio = desligado
SANDBOX_URL=http://localhost:8080

# Comportamento do SDK (consumidas pelo nullain-sdk)
NULLAIN_AGENT__PLAN_COMPLEXITY_THRESHOLD=high      # planeja só trabalho complexo
NULLAIN_WEB_FETCH__SEARXNG_BASE_URL=http://searxng:8080

As duas últimas são do próprio SDK, expostas pelo NullainSettings via pydantic-settings. Qualquer campo aninhado é configurável assim, com o prefixo NULLAIN_ e __ separando os níveis — sem precisar tocar no código.

Deploy

Roda em qualquer plataforma que execute Docker. Em produção usamos Coolify (Docker Compose + Force deploy without cache quando o requirements.txt muda). O repositório também traz manifestos prontos para Railway, Render e Fly.io — veja DEPLOY.md.

docker compose up --build     # local
python main.py --web          # sem container, porta 8000
python main.py                # CLI no terminal

---

Licença

Distribuída sob a licença MIT.
Use, adapte e evolua — com o espírito Nullain.

---

Nullain Agent
<sub>Pensa · Planeja · Executa

movida pelo Nullain Agent SDK

feito com intenção · por netty-linux</sub>