1
🔌 Endpoints principais
Os tres grupos de endpoints que compoe a API do NotebookLMX.
# Notebooks
POST /api/notebooks # Criar notebook
GET /api/notebooks # Listar notebooks
GET /api/notebooks/{id} # Obter notebook
DELETE /api/notebooks/{id} # Deletar notebook
# Sources
POST /api/notebooks/{id}/sources # Upload fonte
GET /api/notebooks/{id}/sources # Listar fontes
DELETE /api/sources/{id} # Remover fonte
# Chat & Generation
POST /api/notebooks/{id}/chat # Enviar mensagem
POST /api/notebooks/{id}/generate # Gerar artefato
2
🎛️ Router structure
Organizacao dos routers em modulos separados.
# app/main.py
from fastapi import FastAPI
from app.routers import notebooks, sources, chat
app = FastAPI(title="NotebookLMX")
app.include_router(notebooks.router, prefix="/api", tags=["notebooks"])
app.include_router(sources.router, prefix="/api", tags=["sources"])
app.include_router(chat.router, prefix="/api", tags=["chat"])
3
🔐 Validacao de acesso
Middleware e dependencies para controle de acesso.
from fastapi import Depends, HTTPException
from app.services.auth import get_current_user
async def verify_notebook_access(
notebook_id: int,
user = Depends(get_current_user)
):
notebook = await get_notebook(notebook_id)
if notebook.owner_id != user.id:
raise HTTPException(403, "Access denied")
return notebook
@router.get("/notebooks/{id}")
async def get_notebook(
notebook = Depends(verify_notebook_access)
):
return notebook
4
📊 Estado e sessoes
Sessao por Notebook
class NotebookSession:
notebook_id: int
sources: List[Source]
chat_history: List[Message]
preferences: Dict
created_at: datetime
Cache em Memoria
# TTL cache para sessoes
sessions: Dict[int, NotebookSession] = {}
async def get_session(id: int):
if id not in sessions:
sessions[id] = await load(id)
return sessions[id]
5
🔄 Middleware GIPM
Middleware que implementa rastreabilidade e auditoria.
@app.middleware("http")
async def gipm_audit_middleware(request: Request, call_next):
request_id = str(uuid4())
start_time = time.time()
# Adiciona ID ao request
request.state.request_id = request_id
response = await call_next(request)
# Log de auditoria
duration = time.time() - start_time
await log_request(
request_id=request_id,
path=request.url.path,
method=request.method,
status=response.status_code,
duration_ms=duration * 1000
)
response.headers["X-Request-ID"] = request_id
return response
6
📋 Schemas e modelos
from pydantic import BaseModel, Field
class ChatRequest(BaseModel):
message: str = Field(..., min_length=1, max_length=10000)
persona: str = Field(default="professional")
output_format: str = Field(default="markdown")
class ChatResponse(BaseModel):
response: str
tokens_used: int
cost_usd: float
request_id: str
timestamp: datetime
7
⚠️ Error handling
from fastapi import HTTPException
from fastapi.responses import JSONResponse
class GIPMException(Exception):
def __init__(self, code: str, message: str, details: dict = None):
self.code = code
self.message = message
self.details = details or {}
@app.exception_handler(GIPMException)
async def gipm_exception_handler(request, exc: GIPMException):
return JSONResponse(
status_code=400,
content={
"error": exc.code,
"message": exc.message,
"details": exc.details,
"request_id": request.state.request_id
}
)
8
📈 Logging estruturado
import structlog
log = structlog.get_logger()
async def process_chat(request: ChatRequest):
log.info(
"chat_request_received",
notebook_id=notebook_id,
message_length=len(request.message),
persona=request.persona
)
result = await pipeline.execute(request)
log.info(
"chat_request_completed",
tokens=result.tokens_used,
cost=result.cost_usd,
duration_ms=result.duration_ms
)
return result
📝 Resumo do Modulo
✓Endpoints - API REST organizada por recurso
✓Middleware - Auditoria automatica de requests
✓Schemas - Validacao forte com Pydantic
✓Logging - Estruturado para analise