[FEATURE] Backend REST API Routes for SKOS Vocabulary Explorer

[ZohaibHassan16]

Summary

The frontend React UI for the Vocabulary Workspace is complete (see PR #420), but the FastAPI backend routes required to serve the data do not currently exist in semantica/explorer/routes/.

To support the UI, we need to implement the vocabulary.py router and append the corresponding Pydantic schemas to schemas.py.

Required Endpoints (semantica/explorer/routes/vocabulary.py)

1. GET /api/vocabulary/schemes
   • Returns: A list of available SKOS vocabularies/ontologies currently loaded in the graph.
2. GET /api/vocabulary/hierarchy
   • Params: scheme (string URI)
   • Returns: A nested JSON tree representing the broader/narrower hierarchy of concepts for the selected scheme.
3. POST /api/vocabulary/import
   • Accepts: UploadFile (multipart/form-data containing .ttl or .rdf files).
   • Action: Parses the file (likely via rdflib) and ingests the SKOS concepts into the current GraphSession.

Required Schemas (semantica/explorer/schemas.py)

class VocabularyScheme(BaseModel):
    uri: str
    label: str
    description: Optional[str] = None

class ConceptNode(BaseModel):
    uri: str
    pref_label: str
    alt_labels: List[str] = Field(default_factory=list)
    children: Optional[List['ConceptNode']] = None

[ZohaibHassan16]

Hey @KaifAhmad1 , I am happy to take ownership of it and open a PR to implement these backend routes so they perfectly match TanStack Query hooks written in the UI PR.

[ZohaibHassan16]

Hey @KaifAhmad1 , writing this to let you know that as when I was going to implement this. I found two things.

A) FastAPI entry point: While looking at semantica/server.py, I noticed that currently only mounts /build and /health endpoints. It doesn't look like the other explorer routes (graph.router, temporal.router etc,.) are included there. Is there a separate FastAPI entry point for the Explorer or should I go ahead and add the include_router call to server.py? I want to make sure I hook vocabulary.router into the correct app instance.

B) For the POST /api/vocabulary/import endpoint, to keep the API route itself clean and testable, my plan is to extract the .ttl file parsing logic into a separate dedicated utility file. IT will use rdflib to parse the file into the standard node/edge dictionaries, which the route will then pass into session.add_nodes() and add_edges(). Does this sounds good?

I want your greenlight before opening issues and iterating from there

[KaifAhmad1]

Hey @KaifAhmad1 , writing this to let you know that as when I was going to implement this. I found two things.

A) FastAPI entry point: While looking at semantica/server.py, I noticed that currently only mounts /build and /health endpoints. It doesn't look like the other explorer routes (graph.router, temporal.router etc,.) are included there. Is there a separate FastAPI entry point for the Explorer or should I go ahead and add the include_router call to server.py? I want to make sure I hook vocabulary.router into the correct app instance.

B) For the POST /api/vocabulary/import endpoint, to keep the API route itself clean and testable, my plan is to extract the .ttl file parsing logic into a separate dedicated utility file. IT will use rdflib to parse the file into the standard node/edge dictionaries, which the route will then pass into session.add_nodes() and add_edges(). Does this sounds good?

I want your greenlight before opening issues and iterating from there

@ZohaibHassan16 Go ahead and implement—add include_router in server.py and keep the RDF parsing as a separate utility, that approach looks solid 👍

[KaifAhmad1]

@ZohaibHassan16 Dude All things done for this Issue including UI Testing?

[ZohaibHassan16]

I have to test it yet (and wire some minor stuff), but yes everything is done for the issue as far as vocabulary workspace is concerned. I am working on something else rn and would let you know in a while if UI PR is ready to be pulled @KaifAhmad1

[KaifAhmad1]

I have to test it yet (and wire some minor stuff), but yes everything is done for the issue as far as vocabulary workspace is concerned. I am working on something else rn and would let you know in a while if UI PR is ready to be pulled @KaifAhmad1

Hey @ZohaibHassan16, great progress.

We need to ship the Knowledge Explorer this week for the KGC Incubator Conference pitch and VC application.

Also, we need a 90-sec pitch/demo video for the KGC startup pitch—can you take the lead on that? It should showcase all major Semantica features. If possible, let’s also create a version for the README and upload it as well.

We should also plan to apply for YC Summer in April, so this will be useful there as well.

Let me know if you need anything from my side.