The Octostar Platform Python SDK

The Octostar Python SDK provides decorators, utilities, and Streamlit components for integrating with the Octostar shell. It is split across three packages that are installed at runtime or via requirements.txt:

Package	Provides
octostar	Auth client, dev_mode, ontology queries
streamlit-octostar-utils	impersonating_running_user, UI helpers
octostar-streamlit	Streamlit components (os_dropzone, os_contextmenu, desktop APIs)

octostar (the Python client) is not in requirements.txt — it is downloaded at container startup by main.sh from the running platform instance.

---

@impersonating_running_user() and @dev_mode()

These two decorators are the Streamlit equivalent of OctostarContextProvider. They establish the authenticated session context and inject an octostar client object into your function.

import os
from octostar.client import dev_mode
from streamlit_octostar_utils.octostar.client import impersonating_running_user

@impersonating_running_user()
@dev_mode(os.environ.get("OS_DEV_MODE"))
def loop(client):
    # client is an authenticated Octostar client
    # all platform SDK calls happen here
    ...

The template uses this pattern in two places:

• initialize(client) — called once per session to set up st.session_state
• loop(client) — called on every Streamlit rerun to render the UI

if not st.session_state.get("initialized"):
    initialize()
if st.session_state.get("initialized"):
    loop()

@dev_mode reads OS_DEV_MODE from the environment. When true (local dev), it impersonates the user set in .env rather than requiring a live platform session.

---

Querying the knowledge graph

The equivalent of OntologyAPI is query_ontology from the Python client:

from octostar.utils.ontology import query_ontology

@impersonating_running_user()
@dev_mode(os.environ.get("OS_DEV_MODE"))
def loop(client):
    results = query_ontology.sync(
        "select * from dtimbr.person where entity_label like '%Robert%'",
        client=client,
    )
    st.json(results)

---

os_dropzone

A drag-and-drop target that accepts entities from the Octostar sidebar — the direct equivalent of OsDropzone:

from octostar_streamlit.components import os_dropzone
from octostar_streamlit.core.components.params import OsDropzoneParams

records = os_dropzone(
    key="dropzone-1",
    params=OsDropzoneParams(label="Drag files here from the sidebar"),
)
if records is not None:
    for item in records:
        st.write(item)

---

os_contextmenu

Renders an entity label with a right-click context menu — the equivalent of the OsContextMenu component:

from octostar_streamlit.components import os_contextmenu
from octostar_streamlit.core.components.params import OsContextMenuParams

os_contextmenu(
    params=OsContextMenuParams(
        item={"entity_type": "person", "entity_id": "123"},
        label="John Doe (person)",
    )
)

---

Desktop APIs

The equivalent of DesktopAPI is the octostar_streamlit.desktop module:

from octostar_streamlit.desktop import (
    get_active_workspace,
    get_open_workspace_ids,
    close_workspace,
    open as desktop_open,
    get_search_results,
)
from octostar_streamlit.core.desktop.params import OpenParams, SearchResultsParams

current_workspace = get_active_workspace()
open_workspaces   = get_open_workspace_ids()

---

UI helpers

from streamlit_octostar_utils.style.common import hide_streamlit_header

# Call at the top of your loop() to remove the default Streamlit header bar
hide_streamlit_header()