AdryanAzul's picture
docs: configure static Space landing page (sdk: static) with full source code
b6eb13c verified
Raw History Blame Contribute Delete
10.4 kB
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>DocuMind AI — Aplicação RAG com Embeddings Locais e BYOK</title>
<style>
:root {
--bg: #0b1020;
--surface: #121933;
--surface-alt: #182142;
--border: #26325c;
--text: #e6ebff;
--muted: #9aa7d1;
--primary: #5b8cff;
--accent: #38d9a9;
--warn-bg: #2a2112;
--warn-border: #d99b26;
--warn-text: #ffd685;
--code-bg: #090d1a;
}
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Inter, sans-serif;
background: linear-gradient(180deg, #090d1a 0%, var(--bg) 100%);
color: var(--text);
line-height: 1.65;
}
.container {
max-width: 1040px;
margin: 0 auto;
padding: 2rem 1.25rem 4rem;
}
header.hero {
background: radial-gradient(circle at top right, rgba(91, 140, 255, 0.18), transparent 55%),
var(--surface);
border: 1px solid var(--border);
border-radius: 16px;
padding: 2.25rem 2rem;
margin-bottom: 1.5rem;
}
.badge-row {
display: flex;
flex-wrap: wrap;
gap: 0.5rem;
margin-bottom: 1rem;
}
.badge {
font-size: 0.78rem;
font-weight: 600;
padding: 0.25rem 0.65rem;
border-radius: 999px;
background: var(--surface-alt);
border: 1px solid var(--border);
color: var(--accent);
}
h1 {
font-size: clamp(1.85rem, 3.5vw, 2.5rem);
line-height: 1.2;
margin-bottom: 0.75rem;
}
.subtitle {
color: var(--muted);
font-size: 1.05rem;
max-width: 780px;
}
.notice {
background: var(--warn-bg);
border: 1px solid var(--warn-border);
color: var(--warn-text);
border-radius: 12px;
padding: 1rem 1.25rem;
margin-bottom: 2rem;
font-size: 0.95rem;
}
section {
margin-bottom: 2rem;
}
h2 {
font-size: 1.35rem;
margin-bottom: 0.9rem;
color: #ffffff;
border-left: 4px solid var(--primary);
padding-left: 0.75rem;
}
.grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
gap: 1rem;
}
.card {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 12px;
padding: 1.25rem;
}
.card h3 {
font-size: 1.05rem;
margin-bottom: 0.5rem;
color: var(--primary);
}
.card p, .card li {
color: var(--muted);
font-size: 0.94rem;
}
.card ul {
padding-left: 1.15rem;
margin-top: 0.4rem;
}
.flow-box {
background: var(--code-bg);
border: 1px solid var(--border);
border-radius: 12px;
padding: 1.1rem 1.25rem;
overflow-x: auto;
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
font-size: 0.88rem;
color: #c8d6ff;
white-space: pre;
}
.tech-list {
display: flex;
flex-wrap: wrap;
gap: 0.6rem;
}
.tech-pill {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 8px;
padding: 0.45rem 0.8rem;
font-size: 0.9rem;
color: var(--text);
}
pre.code {
background: var(--code-bg);
border: 1px solid var(--border);
border-radius: 10px;
padding: 1rem 1.15rem;
overflow-x: auto;
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
font-size: 0.88rem;
color: #d6e2ff;
margin-top: 0.6rem;
}
footer {
margin-top: 3rem;
padding-top: 1.25rem;
border-top: 1px solid var(--border);
color: var(--muted);
font-size: 0.88rem;
text-align: center;
}
</style>
</head>
<body>
<main class="container">
<header class="hero">
<div class="badge-row">
<span class="badge">Python 3.12+</span>
<span class="badge">RAG Modular</span>
<span class="badge">Embeddings Locais (CPU)</span>
<span class="badge">Arquitetura BYOK</span>
</div>
<h1>📄 DocuMind AI</h1>
<p class="subtitle">
Aplicação de <strong>Retrieval-Augmented Generation (RAG)</strong> para indexação de documentos PDF
e perguntas em linguagem natural com respostas fundamentadas exclusivamente no conteúdo enviado e
citação de documento e página.
</p>
</header>
<div class="notice">
<strong>Aviso sobre esta hospedagem:</strong> Este Space utiliza <code>sdk: static</code> para apresentar
a documentação e disponibilizar o código-fonte público. <strong>A demonstração interativa em Streamlit não está
hospedada nesta versão</strong> — siga as instruções abaixo para executar a aplicação localmente.
</div>
<section>
<h2>Arquitetura e Fluxo RAG</h2>
<div class="flow-box">[Upload PDF] ─▶ document_loader.py ─▶ text_splitter.py ─▶ embeddings.py (local) ─▶ vector_store.py (ChromaDB)
│
[Pergunta] ───▶ embeddings.py (local) ───────────────────────▶ retriever.py (Top 3-5) ──────────┘
│
▼
[Resposta + Fontes] ◀── app.py (Streamlit) ◀── rag_pipeline.py ◀── llm.py (BYOK: Gemini / Groq)</div>
</section>
<section>
<h2>Componentes Principais</h2>
<div class="grid">
<article class="card">
<h3>Embeddings Locais (Sentence Transformers)</h3>
<p>
Utiliza <code>sentence-transformers/all-MiniLM-L6-v2</code> localmente na CPU via PyTorch
(384 dimensões). O mesmo modelo é usado na indexação e nas consultas, carregado uma única vez
por processo com cache local e <strong>sem necessidade de API Key</strong>.
</p>
</article>
<article class="card">
<h3>Banco Vetorial (ChromaDB)</h3>
<p>
Armazena textos, vetores e metadados (<code>source</code>, <code>page</code>, <code>chunk_index</code>)
com similaridade de cosseno, filtro de distância máxima (<code>max_distance=0.85</code>), remoção de
<em>chunks</em> órfãos na reindexação e isolamento por coleção/sessão.
</p>
</article>
<article class="card">
<h3>Integração Gemini e Groq</h3>
<p>
Geração via <strong>Google Gemini API</strong> (<code>google-genai</code>) e <strong>Groq API</strong>
via REST (<code>httpx</code>). Os trechos recuperados são enviados como contexto fechado para reduzir
alucinações e citar documento e página.
</p>
</article>
</div>
</section>
<section>
<h2>Funcionamento do BYOK (Bring Your Own Key)</h2>
<div class="grid">
<article class="card">
<h3>Modo Gemini</h3>
<p>Solicita apenas <code>GEMINI_API_KEY</code> na barra lateral e utiliza a Google Gemini API.</p>
</article>
<article class="card">
<h3>Modo Groq</h3>
<p>Solicita apenas <code>GROQ_API_KEY</code> e realiza a geração diretamente pela Groq API.</p>
</article>
<article class="card">
<h3>Modo Gemini + Fallback Groq</h3>
<p>
Usa Gemini como primário e aciona Groq automaticamente apenas em falhas temporárias elegíveis
(<code>429</code>, <code>5xx</code>, <em>timeout</em> ou erro de rede), avisando na interface.
</p>
</article>
</div>
</section>
<section>
<h2>Segurança e Privacidade</h2>
<div class="card">
<ul>
<li><strong>Credenciais apenas em memória:</strong> chaves BYOK ficam somente em <code>st.session_state</code>, nunca são gravadas em disco, no ChromaDB, em logs ou no histórico de chat, e podem ser limpas pelo botão <em>Limpar credenciais</em>.</li>
<li><strong>Sanitização de erros:</strong> padrões de chaves e headers <code>Bearer</code> são mascarados antes de exibição ou log.</li>
<li><strong>Isolamento por sessão:</strong> cada sessão usa token aleatório (<code>secrets.token_urlsafe</code>) e coleção isolada no ChromaDB.</li>
<li><strong>Proteção contra Prompt Injection e DoS:</strong> trechos delimitados em <code>&lt;documentos&gt;</code>, instrução de sistema restritiva e limite de 20 MB por PDF.</li>
</ul>
</div>
</section>
<section>
<h2>Tecnologias Utilizadas</h2>
<div class="tech-list">
<span class="tech-pill">Python 3.12+</span>
<span class="tech-pill">Streamlit</span>
<span class="tech-pill">ChromaDB</span>
<span class="tech-pill">Sentence Transformers</span>
<span class="tech-pill">PyTorch (CPU)</span>
<span class="tech-pill">Google Gemini API</span>
<span class="tech-pill">Groq API (httpx)</span>
<span class="tech-pill">PyPDF</span>
<span class="tech-pill">python-dotenv</span>
<span class="tech-pill">Pytest</span>
</div>
</section>
<section>
<h2>Como Executar Localmente</h2>
<div class="card">
<p>Clone o repositório do Space, crie um ambiente virtual, instale as dependências e inicie o Streamlit:</p>
<pre class="code">git clone https://huggingface.co/spaces/AdryanAzul/DocuMindAI_RAG_Application
cd DocuMindAI_RAG_Application
python -m venv .venv
# Windows (PowerShell): .venv\Scripts\Activate.ps1
# Linux / macOS: source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py</pre>
<p style="margin-top: 0.75rem;">Para executar a suíte de testes automatizados:</p>
<pre class="code">pytest -v</pre>
</div>
</section>
<footer>
DocuMind AI — Repositório público de código-fonte e documentação estática.
</footer>
</main>
</body>
</html>