Glossary

This glossary defines terms as they are used specifically in the OptixLog platform, SDK, and CLI. Terms are listed alphabetically.

API key

A credential of the form sk-opt-... used to authenticate every request to the OptixLog server. Two key types exist:

• service key — bound to an organization, not a person. Used for automated pipelines and CI. Key type reported as "service".
• user key — bound to a specific user account. Key type reported as "user" (the server may return "human" for this type; the CLI normalizes it to "user" in all display output).

Keys are stored in ~/.optixlog/credentials.toml by optixlog login and are never committed to source control. See Credentials File.

codegen

Short for "code generation". The process by which optixlog generate reads a schema contract and emits a typed Python module (optixlog_gen.py by default). The generated module contains node dataclasses, a Projects namespace, per-project union aliases, wrapper classes, and the OptixClient. See Generated Module Anatomy.

edge

A directed relationship between two workflow nodes in a project graph. Two edge directions exist:

• origin edge — points from a predecessor node to the current node (the current node depends on or was derived from the origin).
• forward edge — points from the current node to a successor node (the current node feeds into the forward node).

Edges are supplied at ingest time via the origin_nodes and forward_nodes parameters, or derived automatically from the prompt parameter.

fixture

A local JSON file that conforms to the schema contract format and is used in place of a live server call. Fixtures enable fully offline development and testing. Pass a fixture with --fixture <path> or OPTIXLOG_FIXTURE=<path>. The canonical fixture is python-sdk-spec/tests/fixtures/schema.sample.json.

ingest

The act of writing a typed workflow node into a project graph. Ingest creates the node (or updates it if it already exists) and wires its edges. Performed via PipelineProject.ingest() or the generated _Project_* wrapper's ingest(). Returns an IngestResult.

IngestResult

A frozen dataclass returned by every ingest call:

@dataclass(frozen=True)
class IngestResult:
    project_id: str
    node_id: str
    created: bool           # True = new node; False = updated existing node
    origin_nodes: list[EntityRef]
    forward_nodes: list[EntityRef]

member

A user who belongs to a project's organization and participates in at least one team within that project. Represented by ProjectMember(user_ref: EntityRef, memberships: list[TeamMembership] | None). Retrieved via ManagementProject.get_all_members().

membership

The association between a member and a team, including the member's role in that team and the date they joined. Represented by TeamMembership(user_ref, team_ref, role, joined_at, user, team). Accessed via team.memberships.

node label

A tag applied to a workflow node to classify it within the graph. Labels have an id, a name, and an optional documentation link — a pointer to an uploaded file, exposed as a nested documentation object (with documentation_id as its id). Accessed via WorkflowNodeCollection.labels. Represented by NodeLabel(id, name, documentation_id, documentation).

documentation

A named pointer to an uploaded file (stored in object storage) that documents a node label or workflow schema. Represented by Documentation(id, title, file, created_at, updated_at), where file carries the backing file's metadata. The file's bytes are private — fetch a short-lived signed download URL with project.workflow_nodes.labels.download_documentation(documentation_id).

node type (schema type)

The schema definition of a category of workflow node, as declared in the node_types array of the schema contract. Each node type has a name (e.g. "SimulationNode") and a list of typed fields. The codegen turns each node type into a frozen Python dataclass. See Type Mapping.

OptixClient

The generated entry point class in optixlog_gen.py. It wraps an SDKClient and a Pipeline, resolves credentials automatically, and exposes a project() method with one typed overload per project. Passing a node type that does not belong to a project's schema to project().ingest() is a static type error. See Generated Module Anatomy.

organization

The top-level entity that owns projects, teams, and members. An organization has a stable id (e.g. "org_leidos_01"), a name, and optional contact/company metadata. Accessed via ManagementProject.organization.get(). Represented by Organization(id, name, description, logo_url, ...).

profile

A named credential set in ~/.optixlog/credentials.toml. The default profile is "default". Multiple profiles let you manage credentials for different environments or organizations. Selected with --profile <name> on all CLI commands and resolve_credential(profile=...) in the SDK.

project

A workspace inside an organization where workflow graphs live. Each project has a stable id (e.g. "proj_grating_7f3a"), a name, a status, and optional metadata. Projects are listed in optixlog.toml and their schemas drive codegen. Accessed through Management.project() or Pipeline.project().

ProjectRef

A lightweight reference to a project containing only its id. Used to pass a project between SDK layers without exposing ingest or management operations directly:

@dataclass(frozen=True)
class ProjectRef:
    id: str

Obtained via SDKClient.project(project_id). Passed to Management.project_from() or Pipeline.project_from().

projects namespace

The Projects class in optixlog_gen.py containing Literal-typed string constants for each project id (e.g. Projects.GRATING_COUPLER_LAB = "proj_grating_7f3a"). The Literal annotation is what enables type-safe overload selection on OptixClient.project().

project wrapper

One of the generated _Project_<id> classes in optixlog_gen.py. Each wraps a PipelineProject and constrains ingest so that only node types belonging to that project's schema are accepted. See Generated Module Anatomy.

schema contract

The JSON document fetched from the v0.codegen.schema endpoint (or loaded from a --fixture). It declares the projects, node types, field types, and many-to-many project↔node mapping that drives code generation. Parsed and validated by contract.py into a SchemaContract object. See Schema Contract.

SDKClient

The low-level HTTP client class (optixlog.SDKClient). It manages the connection pool, authentication header, retries, and timeout. Management and Pipeline both accept an SDKClient in their constructors. The generated OptixClient wraps one internally and exposes it via OptixClient.sdk.

team

A named group of members inside a project's organization. Teams have an id, a name, an optional category, and a memberships collection. Represented by Team (not a dataclass; keyword-only __init__). Accessed via ManagementProject.teams.

union alias

A type alias in optixlog_gen.py formed as the |-union of all node dataclasses that belong to a given project (e.g. _GratingCouplerLabNodes = SimulationNode | MeasurementNode). The alias is private and is used only as the data parameter type on the project wrapper's ingest overloads.

workflow node

A typed, property-bearing vertex in a project's workflow graph. Every workflow node has a display_name, an optional node label, typed properties, optional file attachments, and optional parent/child edges. Represented by WorkflowNode. Created by ingesting a node dataclass.