doc-to-nlp-serializer

Serwis REST API do serializacji dokumentów tekstowych w format przygotowany pod uczenie maszynowe — parsing różnych formatów plików, ekstrakcja tekstu i chunking dla modeli NLP.

Tech Stack

Backend & Framework:

• Python 3.12
• Django 5.x
• Django REST Framework 3.14+
• drf-spectacular (OpenAPI/Swagger docs)

Parsowanie dokumentów:

• PyMuPDF (fitz) — parsing PDF
• python-docx — parsing DOCX
• BeautifulSoup4 + lxml — parsing HTML/XML
• python-magic — MIME type detection

Tokenizacja & chunking:

• tiktoken — tokenizacja dla chunkowania tekstu

Infrastructure:

• PostgreSQL (psycopg2-binary)
• Gunicorn (production WSGI server)
• WhiteNoise (static files serving)
• Railway (deployment platform)
• Docker

Setup & Run

Wymagania

• Python 3.12+
• PostgreSQL (lub Railway Postgres)
• libmagic1 (instalowane automatycznie w Dockerfile)

Lokalna instalacja

1. Clone repo:

git clone https://github.com/Wellysa/doc-to-nlp-serializer.git
cd doc-to-nlp-serializer

2. Utwórz virtualenv i zainstaluj dependencies:

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Konfiguracja zmiennych środowiskowych: Skopiuj .env.example → .env i ustaw:

DATABASE_URL=postgres://user:password@localhost:5432/dbname
DEBUG=True
SECRET_KEY=your-secret-key
ALLOWED_HOSTS=localhost,127.0.0.1
CORS_ALLOWED_ORIGINS=http://localhost:3000

4. Migracje i uruchomienie:

python manage.py migrate
python manage.py runserver

API dostępne pod: http://localhost:8000

Deploy na Railway

1. Połącz repo z Railway
2. Railway automatycznie wykrywa railway.json i Dockerfile
3. Ustaw PostgreSQL addon
4. Deploy wykonuje się automatycznie (migrations → gunicorn)

Architektura

doc-to-nlp-serializer/
├── config/               # Główna konfiguracja Django
│   ├── settings.py       # Settings (DB, CORS, DRF, Spectacular)
│   ├── urls.py           # Root URLconf
│   └── wsgi.py           # WSGI entry point
├── parser/               # Aplikacja Django - parsowanie dokumentów
│   ├── models.py         # Modele Django (unverified — potencjalnie Document model)
│   ├── serializers.py    # DRF serializers
│   ├── views.py          # API endpoints (ViewSets/APIViews)
│   ├── urls.py           # Parser app URLs
│   ├── admin.py          # Django admin config
│   └── parsers/          # Moduły parsowania dla różnych formatów
│       ├── base.py       # Bazowa klasa parser
│       ├── factory.py    # Factory pattern - wybór parsera wg MIME type
│       ├── pdf.py        # PDF parser (PyMuPDF)
│       ├── docx.py       # DOCX parser (python-docx)
│       ├── html.py       # HTML parser (BeautifulSoup4)
│       └── txt.py        # Plain text parser
├── requirements.txt      # Python dependencies
├── Dockerfile            # Railway deployment
└── manage.py             # Django CLI

Parser Factory Pattern

Serwis używa factory pattern (parser/parsers/factory.py) do automatycznego wyboru odpowiedniego parsera na podstawie MIME type pliku:

• application/pdf → PDF parser (PyMuPDF)
• application/vnd.openxmlformats-officedocument.wordprocessingml.document → DOCX parser
• text/html → HTML parser (BeautifulSoup4)
• text/plain → TXT parser

Każdy parser dziedziczy z base.py i implementuje interfejs ekstrakcji tekstu.

API Endpoints

(unverified — confirm exact routes in parser/urls.py + config/urls.py)

Swagger UI: GET /api/schema/swagger-ui/ (drf-spectacular)

OpenAPI schema: GET /api/schema/ (JSON/YAML)

Parsowanie dokumentów (endpoint path TBD):

• POST /api/parse/ — upload dokumentu + zwrot sparsowanego tekstu z chunkami
• Wspierane formaty: PDF, DOCX, HTML, TXT
• Response format: JSON z ekstrakcją tekstu + tokeny/chunki (tiktoken-based)

Django Admin: /admin/ — zarządzanie danymi przez panel admina

Features

✅ Multi-format parsing: PDF, DOCX, HTML, plain text
✅ Automatic MIME detection: python-magic wybiera parser
✅ Tokenizacja & chunking: tiktoken do podziału tekstu na chunki dla LLM
✅ REST API: DRF z pełnym OpenAPI schema
✅ CORS support: gotowe do integracji z frontend SPA
✅ Production-ready: Gunicorn + WhiteNoise + PostgreSQL
✅ Railway deployment: zero-config CI/CD

Development

Dodawanie nowego parsera:

1. Utwórz parser/parsers/new_format.py dziedziczący z base.py
2. Zaimplementuj parse() method
3. Zarejestruj w factory.py z odpowiednim MIME type

Uruchomienie testów (unverified — confirm test suite exists):

python manage.py test

Tworzenie migracji:

python manage.py makemigrations
python manage.py migrate

Environment Variables

Zmienna	Opis	Wymagana
DATABASE_URL	PostgreSQL connection string	✅
SECRET_KEY	Django secret key	✅
DEBUG	Debug mode (False w prod)	✅
ALLOWED_HOSTS	Dozwolone hosty (comma-separated)	✅
CORS_ALLOWED_ORIGINS	CORS origins (comma-separated)	❌
PORT	Port serwera (Railway ustawia auto)	❌ (Railway)

Status & Roadmap

Current: Production-ready API dla parsowania dokumentów pod ML/NLP workflows

Potencjalne rozszerzenia (unverified — roadmap TBD):

• [ ] Support dla .odt, .rtf, .epub
• [ ] OCR dla zeskanowanych PDF (tesseract)
• [ ] Batch processing endpoints
• [ ] Async processing z Celery
• [ ] Metadane dokumentów (autor, data, keywords)
• [ ] Caching sparsowanych dokumentów

---

Maintainer: Wellysa
Licencja: TBD (confirm with team)
Feedback: Issues/PR na GitHub