Stack Building Guide

When to use get_stack

Reach for get_stack when you need multiple tools that work well together — not just individually. Typical scenarios:

• Starting a new project from scratch and need a full toolkit
• Migrating from one platform to another and need compatible replacements
• Adding a new capability (e.g., real-time features) that requires several tools
• Evaluating technology stacks for a technical proposal

Step 1: Describe your use case

Provide a use case description and any constraints that matter for your project. The more specific you are, the tighter the recommendations.

{
  "use_case": "real-time analytics dashboard",
  "constraints": {
    "language": "TypeScript",
    "deployment": "cloud"
  }
}

ToolPilot parses the use case into required capability categories — data ingestion, processing, storage, visualization — and finds tools that cover each category while maintaining strong graph edges between them.

Step 2: Understand the results

The response includes a primary stack with each tool categorized by role, plus a compatibility score that reflects how well the tools work together.

{
  "stack": {
    "compatibility_score": 0.91,
    "tools": [
      {
        "name": "kafka",
        "role": "ingestion",
        "health_tier": "healthy",
        "health_score": 94,
        "why": "Industry-standard event streaming — excellent TypeScript client (kafkajs)"
      },
      {
        "name": "apache-flink",
        "role": "processing",
        "health_tier": "healthy",
        "health_score": 88,
        "why": "Real-time stream processing with low latency windowing"
      },
      {
        "name": "clickhouse",
        "role": "storage",
        "health_tier": "healthy",
        "health_score": 90,
        "why": "Column-oriented OLAP database optimized for analytics queries"
      },
      {
        "name": "grafana",
        "role": "visualization",
        "health_tier": "healthy",
        "health_score": 95,
        "why": "Native ClickHouse datasource, real-time dashboard support"
      }
    ]
  },
  "alternative_stacks": [
    {
      "compatibility_score": 0.84,
      "tools": [
        { "name": "redpanda", "role": "ingestion" },
        { "name": "materialize", "role": "processing" },
        { "name": "timescaledb", "role": "storage" },
        { "name": "metabase", "role": "visualization" }
      ]
    }
  ]
}

Understanding the compatibility score

The compatibility score (0–1) is calculated from the RELATED_TO edge weights between every pair of tools in the stack. A score of 0.91 means these tools are frequently used together with strong positive outcomes reported across the community. Lower scores might still be great — they just have fewer data points.

Step 3: Evaluate the stack

Don’t accept a stack blindly. For each tool in the recommendation, check:

• Health score — Are all tools in the healthy tier? A single at-risk tool can bottleneck your entire stack.
• TypeScript support — Since we constrained to TypeScript, verify each tool has quality TS clients and type definitions.
• Cloud deployment — Confirm managed cloud options exist for each tool if that’s your constraint.
• Team familiarity — Graph data can’t account for your team’s existing expertise. A slightly lower-scoring stack your team already knows may ship faster.

Example: Building a data pipeline stack

Let’s walk through a scenario. You’re building a real-time analytics dashboard that ingests event data from multiple sources, processes it for aggregation, stores it for fast queries, and renders live charts.

1. Call get_stack — Describe the use case and constraints (TypeScript, cloud deployment).
2. Review the primary stack — Kafka → Flink → ClickHouse → Grafana. Compatibility score: 0.91. All tools are healthy.
3. Check the alternative — Redpanda → Materialize → TimescaleDB → Metabase. Good option if you want PostgreSQL compatibility over ClickHouse’s columnar speed.
4. Decide — Your team already uses PostgreSQL extensively. You pick the primary stack’s ingestion (Kafka) and processing (Flink), but swap storage to TimescaleDB and visualization to Grafana.
5. Report — As you build, use report_outcome for each tool to strengthen the graph edges between your chosen combination.

Tips for better stack recommendations

• Be specific about the use case — “web app” is too broad; “real-time collaborative document editor” gives ToolPilot real signal to work with.
• Include deployment constraints — Self-hosted and cloud stacks look very different. This single filter removes half the candidates.
• Mention scale expectations — A stack for 100 users/day and one for 1M events/second have almost zero overlap.
• Report outcomes — Stack quality improves as more teams report which combinations worked. Your feedback directly strengthens the graph.