Skip to main content

Best Practices

View as Markdown

Best Practices

Practical guidance for building reliable, maintainable RocketRide pipelines.

Credential management​

Store API keys in environment variables, never in .pipe files.

A .pipe file is plain JSON. If you hard-code an API key, it will end up in version control. Use ${ENV_VAR} substitution in the config instead:

{
  "provider": "llm_openai",
  "config": {
    "profile": "openai-4o",
    "openai-4o": { "apikey": "${ROCKETRIDE_OPENAI_KEY}" }
  }
}

${...} references are expanded server-side when the run is submitted: the SDK sends ROCKETRIDE_-prefixed variables from the client environment, the server merges them over its stored secrets, and only ROCKETRIDE_-prefixed references are substituted. References to any other variable (such as ${OPENAI_API_KEY}) are replaced with <REDACTED>, not passed through.

Credentials are per-node: each node holds only its own key, and nodes do not share credential state. A compromised node config does not expose keys belonging to other nodes in the pipeline.

For production deployments, inject keys via a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler) rather than a .env file.

Choosing a preprocessor​

The preprocessor splits documents into chunks before embedding. The right choice depends on your content and latency budget:

PreprocessorBest forNotes
preprocessor_langchainMost text contentFast, deterministic chunking by character or token count. Good default.
preprocessor_llmSemantic coherence mattersUses an LLM to split at meaningful boundaries. Slower and costs tokens; best for long-form prose where chunk boundaries affect retrieval quality.
preprocessor_codeSource codeSplits at function and class boundaries. Do not use for prose.

Start with preprocessor_langchain and a chunk size of 512–1024 tokens. Only switch to preprocessor_llm if retrieval quality is measurably poor.

Chunk size affects both retrieval precision and embedding cost. Smaller chunks retrieve more precisely but increase the number of embeddings to store and query.

Selecting a memory node​

Memory nodes give an agent conversational context across turns. Choose based on whether that context needs to survive pipeline restarts — the full strategy table lives in Advanced Agents. If you don't need cross-session memory, memory_internal is the right default — it has no external dependencies and no latency overhead.

Agents vs. direct LLM calls​

Use a direct LLM node (llm_openai, llm_anthropic, etc.) when:

  • The task is a single-step transformation: summarise this text, classify this input, translate this sentence.
  • The output schema is predictable.
  • Latency is a concern — agents add at least one extra LLM round-trip.

Use an agent node (agent_rocketride, agent_langchain, etc.) when:

  • The task requires deciding which tool to call based on the input.
  • The task involves multiple steps that depend on intermediate results.
  • You want the model to search, retrieve, compute, or call external APIs as part of answering a question.

A common mistake is wrapping a simple Q&A task in an agent "for flexibility." Start with a direct LLM node; promote to an agent only when the task genuinely requires tool use.

Lane typing​

Data in RocketRide flows through typed lanes. Wiring the wrong lane type is the most common configuration error — the canonical lane table (what each lane carries and which nodes accept it) lives on the Execution Model page.

Common mistake: wiring text to a node that expects questions. Text arrives but the node waits for a question signal and never processes it. Check the node's reference page (the Lanes table) when a node appears to receive data but produces no output.

The VS Code extension highlights lane type mismatches in the canvas before you run the pipeline.

Last updated on