Skip to main content

​
Why Sphinx Is Different

Sphinx is a specialized data science agent that sees your entire working environment. When you send a prompt, Sphinx already knows:
  • Your notebook state — Every cell, its code, outputs, and execution status
  • Your kernel state — All variables, dataframes, imports, and installed packages
  • Your preferences — Rules you’ve configured and knowledge from past sessions
This context awareness means you don’t need to explain what’s already visible. Instead, focus your prompts on what Sphinx can’t see: your goals, business logic, and domain expertise.
Sphinx works iteratively—it generates code, executes it, inspects the results, and continues until the task is complete. You don’t need to guide it step-by-step.

​
Core Principles

​
Focus on outcomes, not implementation

Sphinx knows how to write code. Tell it what you want to achieve, not how to achieve it.
Less EffectiveMore Effective
”Create a pandas dataframe, merge it with the other table, then use matplotlib to create a bar chart""Show me a bar chart of total sales by region"
"Use sklearn to split the data 80/20, then fit a random forest classifier""Build a model to predict customer churn and validate its performance"
"Loop through each row and check if the date is valid""Find and fix any invalid dates in the orders table”

​
Provide context that isn’t visible

Sphinx can see your data, but you should also share the context that is unique to your situation:
  • Business logic: “Revenue should exclude refunds and credits”
  • Domain terminology: “A ‘whale’ is a customer with over $10k lifetime value”
  • Data quirks: “The status column uses legacy codes: 1=active, 2=churned, 3=paused”
  • Quality requirements: “This analysis is for the board—make visualizations presentation-ready”
Example: Adding context
"Analyze customer retention by cohort. Note that our fiscal year starts in April, 
and customers are considered 'retained' if they made at least one purchase in the 
following quarter. Exclude test accounts (emails ending in @internal.co)."

​
Let Sphinx iterate

Sphinx validates its own work and refines its approach when needed. Avoid over-specifying every detail—give it room to explore and course-correct.
Over-specifiedBetter
”Write a SQL query to join orders and customers on customer_id, filter where status=‘active’, group by region, and sum the totals…""Show me total orders by region for active customers"
"Load each CSV, check encodings, if that fails try latin-1, then concatenate and dedupe on id…""Combine all the CSV files in this folder into one dataset"
"Write a SQL query to join orders and customers on customer_id, filter where status=‘active’, group by region, and sum the totals…""Show me total orders by region for active customers”
When you prescribe exact steps, Sphinx follows them literally—even if there’s a simpler approach or if an early step fails. State your goal and let Sphinx figure out the path.
Use Plan Mode when you want to discuss and approve the approach before Sphinx starts executing.
If your prompt reads like pseudocode, you’re probably over-specifying. Step back and describe the outcome instead.

​
Structure complex requests clearly

For multi-part tasks, structure your request so Sphinx can track each component:
Example: Multi-part request
"I need to prepare the Q3 sales data for the executive review:

1. Clean the data — remove duplicates and handle missing values
2. Calculate key metrics — total revenue, average order value, and YoY growth
3. Create visualizations — trend chart for revenue, breakdown by product category
4. Flag anomalies — highlight any metrics that deviate significantly from Q2"

​
Prompting Techniques

Different tasks benefit from different prompting styles:
TechniqueWhen to UseExample
Goal-orientedMost tasks”Find the top 10 customers by lifetime value”
Constraint-basedQuality requirements”Exclude outliers beyond 3 standard deviations”
ComparativeExploration and evaluation”Compare logistic regression vs random forest for this classification task”
Iterative refinementAfter initial output”Make the legend more readable and use our brand colors”
HypotheticalTesting assumptions”What would retention look like if we excluded the first 30 days?”

​
Prompting for visualizations

Be specific about the chart’s purpose and audience:
Good visualization prompts
"Create a line chart showing monthly revenue trends for the past 12 months. 
This is for a stakeholder presentation, so use clean formatting and include 
a trendline."

"Visualize the correlation matrix for all numeric features. Highlight any 
correlations above 0.7 or below -0.3."

"Show the distribution of response times with a histogram. Use log scale 
if the data is heavily skewed."

​
Prompting for analysis

State the question you’re trying to answer:
Good analysis prompts
"What factors are most predictive of customer churn? Look at both 
demographic features and behavioral signals."

"Is there a statistically significant difference in conversion rates 
between the control and test groups?"

"Identify any seasonality patterns in the sales data and quantify 
their impact."

​
Prompting for modeling

Define success criteria and validation approach:
Good modeling prompts
"Build a model to predict order value for new customers. Optimize for 
RMSE and use time-based validation to avoid leakage—train on data 
before June, validate on June-July."

"Train a classifier to detect fraudulent transactions. We care more 
about catching fraud (recall) than avoiding false positives, so 
optimize accordingly."

​
Leveraging Built-in Features

​
Rules for persistent instructions

Use Rules to encode instructions that apply across sessions: SPHINX.md — Project-specific conventions in your workspace: 
# Analytics Project Rules

- Use plotly for all visualizations (stakeholders prefer interactive charts)
- Revenue calculations must exclude returns and credits
- Always include sample sizes in chart titles
User Rules — Personal preferences across all projects:
  • “Use type hints in all function definitions”
  • “For all plots, ‘Palatino Linotype’ is the font that should be used”
  • “Add docstrings to any functions you create”
Rules are ideal for conventions you’d otherwise repeat in every prompt. If you find yourself adding the same instruction frequently, make it a rule.

​
Memories for persistent knowledge

Use Memories to capture knowledge that spans sessions:
When to create memories
"Remember that the customer_id in the orders table maps to id in the 
legacy_customers table, not the new customers table."

"Remember that Q4 2024 data is incomplete—we migrated systems in December 
and lost 3 days of data."

"Remember that our churn definition is 90 days of inactivity, not account 
cancellation."
Memories work best for stable facts about your data and domain—things that won’t change week to week.

​
Choosing the right engine

Different engines suit different tasks:
EngineBest For
Memphis (default)Complex multi-step analysis, most general work
CairoPresentation-quality visualizations, thorough edge case handling
SiwaQuick iterations, simple transformations, cost-sensitive work
ThebesExtremely large notebooks requiring maximum context

​
Guardrails for safety

Configure Guardrails to match your risk tolerance:
  • Strict mode: Approve all code before execution (best for production data)
  • Standard mode: Approve potentially risky operations (default)
  • Permissive mode: Minimal interruptions (best for exploratory work)
Add specific patterns to “code to avoid” when you have known dangerous operations in your environment.