PictoGlyph

System architecture: Java, PostgreSQL and Python

The core application is Java 21 with Spring Boot, REST controllers, JPA and a PostgreSQL 16 database. The Java side handles domain entities, ingestion jobs, review decisions, dataset readiness and the tracking of model outputs. Its job is to retain evidence about what was processed and why, rather than ask a vision model to become the sole source of historical truth.

A separate Python/FastAPI service owns image preprocessing and embedding-model execution. The codebase contains a GPU-dependent SigLIP2 model implementation, as well as a deterministic mock embedding model used to support development. A versioned JSON processing contract connects the services. Keeping image processing behind that boundary allows vision experiments to change without rewriting the Java data and review workflow.

Data model: provenance before prediction

A symbol record belongs to a language and can carry its symbol code, image location and JSON metadata. Ingestion services keep track of source jobs and items requiring review; duplicate sign codes can be skipped, while unsupported files are sent for manual processing. The wider research design also considers place, chronology, artefact and trade-route context, but not every intended relationship is yet an end-to-end validated feature.

An ML embedding record retains the symbol identifier, processing job, model name and version, model profile, vector dimension, preprocessing metadata and original input checksum. A separate dataset-release path only queues approved, labelled sign crops after checking that the current image checksum matches the stored source checksum. This helps prevent a quiet change in an image from invalidating later comparisons.

Reasoning: evidence is not a translation

The Java ContextAgent collects evidence from tools that examine questions such as language, place and date, alongside a symbol-similarity tool that calls the Python service. It sorts evidence by its reported confidence and assembles a provisional hypothesis with the supporting items. In the current implementation, the conclusion remains deliberately cautious and its score is a simple average of evidence confidence, not a calibrated probability.

An important limitation is that the symbol-similarity endpoint currently returns fixed mock candidates; it must not be confused with validated nearest-neighbour retrieval. The SigLIP2 embedding implementation and the similarity API solve different problems. Image embeddings alone do not identify a language, decipher an unknown script or establish historical context.

Testing strategy and engineering trade-offs

The repository includes Java tests for ingestion checksums, source mapping and schema drift, review and retry logic, agent tools, ML job contracts and embedding persistence. The Python service includes processing API tests. These tests support correctness of the surrounding software; they do not, by themselves, measure accuracy on unseen historical artefacts.

For future experiments, the useful comparison is visual similarity alone versus historical metadata alone versus a combination of both. Splitting datasets by artefact or source, rather than randomly distributing nearly identical sign crops across train and test sets, is important to avoid inflated results. Model versions, preprocessing and source provenance should remain attached to every recorded result.

• Keep PostgreSQL as the primary evidence store. PostgreSQL/pgvector is a candidate for metadata-aware vector retrieval; FAISS is deferred unless comparative benchmarks justify an additional search system.
• Report ranking quality, uncertainty, failure cases and annotation disagreements rather than a single headline accuracy.
• Treat visual similarity, proposed linguistic relationships and genuine decipherment as different claims requiring different evidence.