Docs Para Markdown API

API para conversão assíncrona de documentos e páginas em chunks estruturados, com opção de retornar também o texto completo em Markdown.

O processamento é feito em segundo plano com fila Redis + RQ. A API apenas recebe a requisicao, cria o job e expoe o status da execucao.

Estrutura do Projeto

src/
  app.py                  # API HTTP e rotas administrativas
  worker.py               # Inicializacao do worker RQ
  tasks.py                # Ponto de entrada dos jobs em segundo plano
  document_processor.py   # Conversao com Docling e geracao de chunks
  rq_helpers.py           # Helpers de compatibilidade para APIs de resultado/job id do RQ
  auth/
    config.py
    models.py
    repository.py
    validators.py

Variaveis de Ambiente

Use .env.example como base.

Principais variaveis:

• APP_NAME
• APP_VERSION
• APP_ORIGINS
• HF_TOKEN
• EMBEDDING_MODEL
• MAX_TOKENS
• DOCS_URL_ENABLED
• ADMIN_DOCS_ENABLED
• ADMIN_API_TOKENS
• TOKEN_DB_PATH

Observacoes:

• ADMIN_API_TOKENS aceita um ou mais tokens administrativos separados por virgula.
• TOKEN_DB_PATH usa data/tokens.db por padrao e e utilizado pelo container da API.
• HF_TOKEN e repassado ao worker para autenticar downloads de modelos quando necessario.

Autenticacao

Token de usuario

POST /document_to_markdown exige:

Authorization: Bearer <user-token>

Os tokens de usuario sao armazenados em SQLite e podem ser gerenciados pelas rotas administrativas.

Token administrativo

As rotas administrativas exigem:

Authorization: Bearer <admin-token>

O token administrativo e lido de ADMIN_API_TOKENS no .env.

Endpoints da API

Publicos

• GET /
• GET /status/{task_id}

Rota protegida de usuario

• POST /document_to_markdown

Campos do formulario:

• url obrigatorio
• include_full_text opcional, booleano, padrao false

Rotas administrativas

• GET /admin/tokens
• POST /admin/tokens
• PATCH /admin/tokens/{token_id}
• DELETE /admin/tokens/{token_id}

As rotas administrativas podem ser ocultadas do Swagger com ADMIN_DOCS_ENABLED=false. O proprio Swagger pode ser desabilitado com DOCS_URL_ENABLED=false.

Execucao com Docker

1. Preparar o .env

cp .env.example .env

No minimo, defina:

APP_NAME="Docs Para Markdown"
APP_VERSION="1.0.0"
ADMIN_API_TOKENS="admin-token"
HF_TOKEN=""

2. Garantir que os diretorios locais obrigatorios existam

O docker-compose.yml atual monta estes caminhos a partir da maquina host:

• ./db -> banco SQLite de tokens
• ./models -> cache de modelos

Crie-os se necessario:

mkdir -p db models

3. Garantir que a rede Docker exista

O arquivo de compose usa a rede externa proxy.

Se ela ainda nao existir:

docker network create proxy

4. Construir e iniciar a stack

docker compose up -d --build

Servicos:

• converter_markdown_api
• converter_markdown_worker
• converter_markdown_redis

A API ficara disponivel em:

http://localhost:8000

Primeiro Uso

1. Criar um token de usuario

curl -X POST http://localhost:8000/admin/tokens \
  -H "Authorization: Bearer admin-token" \
  -H "Content-Type: application/json" \
  -d '{"token":"client-token","active":true}'

2. Enfileirar uma conversao de documento

curl -X POST http://localhost:8000/document_to_markdown \
  -H "Authorization: Bearer client-token" \
  -F "url=https://example.com/document.pdf" \
  -F "include_full_text=true"

Exemplo de resposta:

{
  "task_id": "job-id",
  "status": "queued"
}

3. Consultar o status do job

curl http://localhost:8000/status/job-id

Quando concluir, a resposta tera este formato:

{
  "status": "done",
  "elapsed_seconds": 12.34,
  "result": {
    "chunks": [
      {
        "text": "chunk text",
        "meta": {}
      }
    ],
    "document": "# Full markdown text"
  }
}

Se include_full_text=false, o campo document e omitido.

Persistencia

• O banco de tokens e persistido via ./db:/app/data
• O cache de modelos e persistido via ./models:/models