# Explorador de Conhecimento com IA

> Coloque ficheiros (documentos ou código-fonte) num chatbot. O agente extrai entidades, conceitos e relações (ou módulos, classes, funções e dependências) e, em seguida, apresenta um grafo de conhecimento interativo que você pode explorar.

- Fonte: https://doutorai.pt/apps/ai-knowledge-explorer
- Categoria: Interfaces Generativas
- Dificuldade: Avançado
- Modelos: OpenAI, Claude, Gemini
- Frameworks: CrewAI, LangChain, AutoGen/AG2
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: OPENAI_API_KEY, SECRET_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# AI Knowledge Explorer

Arraste ficheiros (documentos ou código-fonte) para um chatbot. O agente extrai entidades, conceitos e relações (ou módulos, classes, funções e dependências) e, em seguida, renderiza um grafo de conhecimento interativo que você pode explorar.

Clique num nó para ver os detalhes. Faça duplo clique para o expandir: o agente extrai subconceitos (ou subcomponentes, no caso de código) e adiciona-os ao grafo. Faça perguntas no chat para navegar.

![Demo](/assets/apps-img/20e57c71c60a8911.gif)

## Como Funciona

1. **Largue ficheiros**: arraste documentos (`.txt`, `.md`, `.json`, `.csv`) ou ficheiros de código (`.py`, `.ts`, `.js`, `.java`, `.go`, `.rs`, entre outros) para o canvas
2. **O agente extrai**: o LLM identifica a estrutura (entidades e conceitos para texto, módulos e funções para código)
3. **O grafo é renderizado**: os nós e as arestas aparecem à medida que o agente processa cada ficheiro
4. **Você explora**: clique nos nós, expanda-os, faça perguntas e oriente o agente

## Arquitetura

- **Estado partilhado**: o grafo de conhecimento (nós + arestas) vive no estado do agente e é sincronizado bidirecionalmente via CopilotKit v2
- **UI generativa**: cada chamada de ferramenta produz alterações visíveis (novos nós, novas arestas, detalhes expandidos)
- **Human-in-the-loop**: clique para selecionar, faça duplo clique para expandir e use o chat para orientar

### Stack Tecnológica

| Camada | Tecnologia |
|---|---|
| Frontend | Next.js 16, React 19, TailwindCSS 4 |
| Agente | LangGraph (Python), CopilotKit Middleware |
| Grafo | react-force-graph-2d |
| LLM | OpenAI (configurável via variáveis de ambiente) |
| Protocolo | AG-UI (streaming de estado) |

**Sobre o modelo predefinido (`gpt-4o`)**: a extração (`extract_knowledge`, `find_connections`, `expand_node`) funciona ao pedir ao modelo que devolva JSON em bruto e ao analisá-lo de seguida: não existe um esquema de function calling nem um modo de saída estruturada ajustado especificamente ao gpt-4o, pelo que qualquer modelo com boa capacidade de seguir instruções deve funcionar como substituição direta via `OPENAI_MODEL`. O gpt-4o foi escolhido como uma base de referência bem compreendida e económica, por seguir de forma fiável a instrução de devolver apenas JSON, e não porque tenha sido avaliado comparativamente com modelos mais recentes para esta tarefa. Se trocar para um modelo mais recente ou focado em raciocínio, espere que funcione, mas verifique novamente se a instrução "ONLY valid JSON" continua a ser respeitada (alguns modelos envolvem a saída em explicações ou markdown mesmo quando lhes é dito para não o fazer).

## Pré-requisitos

- Node.js 18+
- Python 3.12
- [uv](https://docs.astral.sh/uv/): as dependências Python do agente são geridas com o uv, e o `npm install` executa `uv sync` automaticamente. Instale-o com `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) ou `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows). O uv obtém o Python 3.12 por você, caso ainda não esteja instalado.

## Configuração

```bash
# 1. Install dependencies (also runs `uv sync` for the Python agent)
npm install

# 2. Set your API key
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# 3. Start the app
npm run dev
```

Isto inicia tanto o frontend Next.js (porta 3000) como o agente LangGraph (porta 8125). No Windows, os mesmos scripts `npm` executam os equivalentes `.bat` em `scripts/`.

## Conteúdo de Exemplo

Dois conjuntos de exemplos integrados permitem-lhe experimentar ambos os modos: clique nos botões do estado vazio para os carregar instantaneamente.

**Documentos** (3 ficheiros Markdown sobre agentes de IA):

- `what-are-agents.md`: define agentes, componentes principais (LLM, ferramentas, memória, planeamento)
- `agent-frameworks.md`: compara LangGraph, CrewAI, AutoGen, CopilotKit
- `agent-challenges.md`: alucinação, fiabilidade das ferramentas, avaliação, custo, segurança

Grafo esperado: ~15-22 nós, ~20-33 arestas que cobrem o ecossistema de agentes de IA.

**Base de Código** (3 ficheiros Python que formam um sistema de autenticação FastAPI):

- `auth.py`: criação de tokens JWT, hashing de palavras-passe, classe TokenService
- `routes.py`: endpoints de login, registo e refresh, injeção de dependências
- `models.py`: modelos User, Post e AuditLog do SQLAlchemy

Grafo esperado: ~20 nós que mostram módulos, classes, funções e as respetivas relações de imports/calls/extends.

## Ferramentas do Agente

| Ferramenta | Finalidade |
|---|---|
| `extract_knowledge` | Analisa documentos ou código, extrai entidades/conceitos/relações ou módulos/classes/funções |
| `find_connections` | Descobre ligações mais profundas entre nós existentes |
| `expand_node` | Explora um nó em profundidade: adiciona subconceitos e detalhe |

## Estrutura do Projeto

```
ai-knowledge-explorer/
├── agent/                    # Python LangGraph agent
│   ├── main.py               # Agent entry point
│   └── src/
│       ├── state.py           # KnowledgeState schema
│       └── tools.py           # extract, connect, expand tools
├── src/                       # Next.js frontend
│   ├── app/
│   │   ├── page.tsx           # Main page (chat + graph canvas)
│   │   ├── layout.tsx         # CopilotKit v2 provider
│   │   └── api/
│   │       ├── copilotkit/    # CopilotKit runtime route
│   │       └── upload/        # File upload endpoint
│   ├── components/
│   │   ├── KnowledgeGraph.tsx  # Force-directed graph visualization
│   │   ├── NodeDetail.tsx      # Detail panel on node select
│   │   └── ToolReasoning.tsx   # Tool call status indicators
│   ├── hooks/
│   │   ├── use-knowledge-ui.tsx
│   │   └── use-suggestions.tsx
│   └── lib/
│       ├── types.ts            # KnowledgeNode, KnowledgeEdge types
│       └── example-content.ts  # Built-in example documents and code
├── package.json
└── .env.example
```

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/ai-knowledge-explorer