AdryanAzul commited on
Commit
b6eb13c
·
verified ·
1 Parent(s): 68e8c03

docs: configure static Space landing page (sdk: static) with full source code

Browse files
Files changed (2) hide show
  1. README.md +5 -10
  2. index.html +315 -0
README.md CHANGED
@@ -3,9 +3,7 @@ title: DocuMind AI
3
  emoji: 📄
4
  colorFrom: blue
5
  colorTo: indigo
6
- sdk: streamlit
7
- sdk_version: 1.67.0
8
- app_file: app.py
9
  pinned: false
10
  ---
11
 
@@ -110,14 +108,11 @@ pytest -v
110
 
111
  ---
112
 
113
- ## 🚀 Deploy no Hugging Face Spaces e Limitações
114
 
115
- - O repositório possui o cabeçalho YAML configurado para **Streamlit** (`sdk: streamlit`, `app_file: app.py`).
116
- - **Sem chaves do proprietário:** o Space inicializa normalmente sem exigir `Secrets` globais, pois cada visitante informa sua própria chave na interface.
117
- - **Limitações do plano gratuito:**
118
- - **Disco efêmero:** documentos indexados na sessão são temporários e descartados quando o Space hiberna ou reinicia.
119
- - **CPU e Memória:** embeddings rodam na CPU; para manter boa responsividade, há limite de **20 MB por arquivo PDF**.
120
- - **Primeiro carregamento:** o download inicial dos pesos de `all-MiniLM-L6-v2` ocorre uma vez ao subir o container.
121
 
122
  ---
123
 
 
3
  emoji: 📄
4
  colorFrom: blue
5
  colorTo: indigo
6
+ sdk: static
 
 
7
  pinned: false
8
  ---
9
 
 
108
 
109
  ---
110
 
111
+ ## 🚀 Publicação Estática no Hugging Face Spaces
112
 
113
+ - O repositório utiliza **`sdk: static`** no cabeçalho YAML para servir a página de apresentação (`index.html`) junto com todo o código-fonte em Python.
114
+ - **Aviso:** a demonstração interativa em Streamlit (`app.py`) **não** é executada no Space estático; para usar a interface interativa, siga as instruções de **Instalação e Execução Local** acima.
115
+ - **Arquitetura preparada para nuvem:** o código em `app.py` e `src/` já contempla isolamento por sessão (`SPACE_ID`), arquitetura BYOK em memória e limite de **20 MB por arquivo PDF**.
 
 
 
116
 
117
  ---
118
 
index.html ADDED
@@ -0,0 +1,315 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <!DOCTYPE html>
2
+ <html lang="pt-BR">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>DocuMind AI — Aplicação RAG com Embeddings Locais e BYOK</title>
7
+ <style>
8
+ :root {
9
+ --bg: #0b1020;
10
+ --surface: #121933;
11
+ --surface-alt: #182142;
12
+ --border: #26325c;
13
+ --text: #e6ebff;
14
+ --muted: #9aa7d1;
15
+ --primary: #5b8cff;
16
+ --accent: #38d9a9;
17
+ --warn-bg: #2a2112;
18
+ --warn-border: #d99b26;
19
+ --warn-text: #ffd685;
20
+ --code-bg: #090d1a;
21
+ }
22
+
23
+ * {
24
+ box-sizing: border-box;
25
+ margin: 0;
26
+ padding: 0;
27
+ }
28
+
29
+ body {
30
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Inter, sans-serif;
31
+ background: linear-gradient(180deg, #090d1a 0%, var(--bg) 100%);
32
+ color: var(--text);
33
+ line-height: 1.65;
34
+ }
35
+
36
+ .container {
37
+ max-width: 1040px;
38
+ margin: 0 auto;
39
+ padding: 2rem 1.25rem 4rem;
40
+ }
41
+
42
+ header.hero {
43
+ background: radial-gradient(circle at top right, rgba(91, 140, 255, 0.18), transparent 55%),
44
+ var(--surface);
45
+ border: 1px solid var(--border);
46
+ border-radius: 16px;
47
+ padding: 2.25rem 2rem;
48
+ margin-bottom: 1.5rem;
49
+ }
50
+
51
+ .badge-row {
52
+ display: flex;
53
+ flex-wrap: wrap;
54
+ gap: 0.5rem;
55
+ margin-bottom: 1rem;
56
+ }
57
+
58
+ .badge {
59
+ font-size: 0.78rem;
60
+ font-weight: 600;
61
+ padding: 0.25rem 0.65rem;
62
+ border-radius: 999px;
63
+ background: var(--surface-alt);
64
+ border: 1px solid var(--border);
65
+ color: var(--accent);
66
+ }
67
+
68
+ h1 {
69
+ font-size: clamp(1.85rem, 3.5vw, 2.5rem);
70
+ line-height: 1.2;
71
+ margin-bottom: 0.75rem;
72
+ }
73
+
74
+ .subtitle {
75
+ color: var(--muted);
76
+ font-size: 1.05rem;
77
+ max-width: 780px;
78
+ }
79
+
80
+ .notice {
81
+ background: var(--warn-bg);
82
+ border: 1px solid var(--warn-border);
83
+ color: var(--warn-text);
84
+ border-radius: 12px;
85
+ padding: 1rem 1.25rem;
86
+ margin-bottom: 2rem;
87
+ font-size: 0.95rem;
88
+ }
89
+
90
+ section {
91
+ margin-bottom: 2rem;
92
+ }
93
+
94
+ h2 {
95
+ font-size: 1.35rem;
96
+ margin-bottom: 0.9rem;
97
+ color: #ffffff;
98
+ border-left: 4px solid var(--primary);
99
+ padding-left: 0.75rem;
100
+ }
101
+
102
+ .grid {
103
+ display: grid;
104
+ grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
105
+ gap: 1rem;
106
+ }
107
+
108
+ .card {
109
+ background: var(--surface);
110
+ border: 1px solid var(--border);
111
+ border-radius: 12px;
112
+ padding: 1.25rem;
113
+ }
114
+
115
+ .card h3 {
116
+ font-size: 1.05rem;
117
+ margin-bottom: 0.5rem;
118
+ color: var(--primary);
119
+ }
120
+
121
+ .card p, .card li {
122
+ color: var(--muted);
123
+ font-size: 0.94rem;
124
+ }
125
+
126
+ .card ul {
127
+ padding-left: 1.15rem;
128
+ margin-top: 0.4rem;
129
+ }
130
+
131
+ .flow-box {
132
+ background: var(--code-bg);
133
+ border: 1px solid var(--border);
134
+ border-radius: 12px;
135
+ padding: 1.1rem 1.25rem;
136
+ overflow-x: auto;
137
+ font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
138
+ font-size: 0.88rem;
139
+ color: #c8d6ff;
140
+ white-space: pre;
141
+ }
142
+
143
+ .tech-list {
144
+ display: flex;
145
+ flex-wrap: wrap;
146
+ gap: 0.6rem;
147
+ }
148
+
149
+ .tech-pill {
150
+ background: var(--surface);
151
+ border: 1px solid var(--border);
152
+ border-radius: 8px;
153
+ padding: 0.45rem 0.8rem;
154
+ font-size: 0.9rem;
155
+ color: var(--text);
156
+ }
157
+
158
+ pre.code {
159
+ background: var(--code-bg);
160
+ border: 1px solid var(--border);
161
+ border-radius: 10px;
162
+ padding: 1rem 1.15rem;
163
+ overflow-x: auto;
164
+ font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
165
+ font-size: 0.88rem;
166
+ color: #d6e2ff;
167
+ margin-top: 0.6rem;
168
+ }
169
+
170
+ footer {
171
+ margin-top: 3rem;
172
+ padding-top: 1.25rem;
173
+ border-top: 1px solid var(--border);
174
+ color: var(--muted);
175
+ font-size: 0.88rem;
176
+ text-align: center;
177
+ }
178
+ </style>
179
+ </head>
180
+ <body>
181
+ <main class="container">
182
+ <header class="hero">
183
+ <div class="badge-row">
184
+ <span class="badge">Python 3.12+</span>
185
+ <span class="badge">RAG Modular</span>
186
+ <span class="badge">Embeddings Locais (CPU)</span>
187
+ <span class="badge">Arquitetura BYOK</span>
188
+ </div>
189
+ <h1>📄 DocuMind AI</h1>
190
+ <p class="subtitle">
191
+ Aplicação de <strong>Retrieval-Augmented Generation (RAG)</strong> para indexação de documentos PDF
192
+ e perguntas em linguagem natural com respostas fundamentadas exclusivamente no conteúdo enviado e
193
+ citação de documento e página.
194
+ </p>
195
+ </header>
196
+
197
+ <div class="notice">
198
+ <strong>Aviso sobre esta hospedagem:</strong> Este Space utiliza <code>sdk: static</code> para apresentar
199
+ a documentação e disponibilizar o código-fonte público. <strong>A demonstração interativa em Streamlit não está
200
+ hospedada nesta versão</strong> — siga as instruções abaixo para executar a aplicação localmente.
201
+ </div>
202
+
203
+ <section>
204
+ <h2>Arquitetura e Fluxo RAG</h2>
205
+ <div class="flow-box">[Upload PDF] ─▶ document_loader.py ─▶ text_splitter.py ─▶ embeddings.py (local) ─▶ vector_store.py (ChromaDB)
206
+ │
207
+ [Pergunta] ───▶ embeddings.py (local) ───────────────────────▶ retriever.py (Top 3-5) ──────────┘
208
+ │
209
+ ▼
210
+ [Resposta + Fontes] ◀── app.py (Streamlit) ◀── rag_pipeline.py ◀── llm.py (BYOK: Gemini / Groq)</div>
211
+ </section>
212
+
213
+ <section>
214
+ <h2>Componentes Principais</h2>
215
+ <div class="grid">
216
+ <article class="card">
217
+ <h3>Embeddings Locais (Sentence Transformers)</h3>
218
+ <p>
219
+ Utiliza <code>sentence-transformers/all-MiniLM-L6-v2</code> localmente na CPU via PyTorch
220
+ (384 dimensões). O mesmo modelo é usado na indexação e nas consultas, carregado uma única vez
221
+ por processo com cache local e <strong>sem necessidade de API Key</strong>.
222
+ </p>
223
+ </article>
224
+
225
+ <article class="card">
226
+ <h3>Banco Vetorial (ChromaDB)</h3>
227
+ <p>
228
+ Armazena textos, vetores e metadados (<code>source</code>, <code>page</code>, <code>chunk_index</code>)
229
+ com similaridade de cosseno, filtro de distância máxima (<code>max_distance=0.85</code>), remoção de
230
+ <em>chunks</em> órfãos na reindexação e isolamento por coleção/sessão.
231
+ </p>
232
+ </article>
233
+
234
+ <article class="card">
235
+ <h3>Integração Gemini e Groq</h3>
236
+ <p>
237
+ Geração via <strong>Google Gemini API</strong> (<code>google-genai</code>) e <strong>Groq API</strong>
238
+ via REST (<code>httpx</code>). Os trechos recuperados são enviados como contexto fechado para reduzir
239
+ alucinações e citar documento e página.
240
+ </p>
241
+ </article>
242
+ </div>
243
+ </section>
244
+
245
+ <section>
246
+ <h2>Funcionamento do BYOK (Bring Your Own Key)</h2>
247
+ <div class="grid">
248
+ <article class="card">
249
+ <h3>Modo Gemini</h3>
250
+ <p>Solicita apenas <code>GEMINI_API_KEY</code> na barra lateral e utiliza a Google Gemini API.</p>
251
+ </article>
252
+ <article class="card">
253
+ <h3>Modo Groq</h3>
254
+ <p>Solicita apenas <code>GROQ_API_KEY</code> e realiza a geração diretamente pela Groq API.</p>
255
+ </article>
256
+ <article class="card">
257
+ <h3>Modo Gemini + Fallback Groq</h3>
258
+ <p>
259
+ Usa Gemini como primário e aciona Groq automaticamente apenas em falhas temporárias elegíveis
260
+ (<code>429</code>, <code>5xx</code>, <em>timeout</em> ou erro de rede), avisando na interface.
261
+ </p>
262
+ </article>
263
+ </div>
264
+ </section>
265
+
266
+ <section>
267
+ <h2>Segurança e Privacidade</h2>
268
+ <div class="card">
269
+ <ul>
270
+ <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>
271
+ <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>
272
+ <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>
273
+ <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>
274
+ </ul>
275
+ </div>
276
+ </section>
277
+
278
+ <section>
279
+ <h2>Tecnologias Utilizadas</h2>
280
+ <div class="tech-list">
281
+ <span class="tech-pill">Python 3.12+</span>
282
+ <span class="tech-pill">Streamlit</span>
283
+ <span class="tech-pill">ChromaDB</span>
284
+ <span class="tech-pill">Sentence Transformers</span>
285
+ <span class="tech-pill">PyTorch (CPU)</span>
286
+ <span class="tech-pill">Google Gemini API</span>
287
+ <span class="tech-pill">Groq API (httpx)</span>
288
+ <span class="tech-pill">PyPDF</span>
289
+ <span class="tech-pill">python-dotenv</span>
290
+ <span class="tech-pill">Pytest</span>
291
+ </div>
292
+ </section>
293
+
294
+ <section>
295
+ <h2>Como Executar Localmente</h2>
296
+ <div class="card">
297
+ <p>Clone o repositório do Space, crie um ambiente virtual, instale as dependências e inicie o Streamlit:</p>
298
+ <pre class="code">git clone https://huggingface.co/spaces/AdryanAzul/DocuMindAI_RAG_Application
299
+ cd DocuMindAI_RAG_Application
300
+ python -m venv .venv
301
+ # Windows (PowerShell): .venv\Scripts\Activate.ps1
302
+ # Linux / macOS: source .venv/bin/activate
303
+ pip install -r requirements.txt
304
+ streamlit run app.py</pre>
305
+ <p style="margin-top: 0.75rem;">Para executar a suíte de testes automatizados:</p>
306
+ <pre class="code">pytest -v</pre>
307
+ </div>
308
+ </section>
309
+
310
+ <footer>
311
+ DocuMind AI — Repositório público de código-fonte e documentação estática.
312
+ </footer>
313
+ </main>
314
+ </body>
315
+ </html>