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": { "apikey": "${OPENAI_API_KEY}" } }

The engine expands ${...} references at startup from the process environment.

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:

Preprocessor	Best for	Notes
preprocessor_langchain	Most text content	Fast, deterministic chunking by character or token count. Good default.
preprocessor_llm	Semantic coherence matters	Uses an LLM to split at meaningful boundaries. Slower and costs tokens; best for long-form prose where chunk boundaries affect retrieval quality.
preprocessor_code	Source code	Splits 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:

Node	Scope	Use when
memory_internal	In-process, single session	The conversation is self-contained and can reset on restart. Zero external dependencies.
memory_persistent	Persisted to a store, cross-session	The agent must remember previous conversations. Requires a configured backing store.
tool_mem0	Semantic, long-term	The agent benefits from extracted facts and preferences rather than raw history. Requires a Mem0 account or self-hosted instance.

If you don't need cross-session memory, memory_internal is the right default — it has no 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.

Lane	Carries	Accepted by
questions	User queries / prompts	LLMs, vector stores (for retrieval), agents
answers	LLM responses	response target, downstream nodes expecting generated text
text	Raw or parsed text	Preprocessors, embedding nodes, LLMs
tags	File metadata objects	Parsers, embedding nodes
documents	Vector-ready chunks	Vector store documents input
image / audio / video	Media	Vision/audio/video nodes

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.

Related

• Concepts: Execution Model: how lanes carry data.
• Concepts: Agents & Tools: when agents are the right abstraction.
• Concepts: Error Handling: what happens when things go wrong.