> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis/org-genie.md).

# Org Genie

Use Org Genie to ask ad hoc questions about your org's observability data and metadata changes using AI-powered conversational queries.

Org Genie is Pharos's AI-powered conversational interface that enables you to ask natural language questions about your Salesforce org's observability data and metadata changes. Rather than building complex reports or manually analyzing data, you can have a conversation to quickly get insights, identify patterns, and understand what's happening in your org.

{% hint style="success" %}
**Conversational Observability**

Transform hours of dashboard building and report filtering into seconds of natural language conversation. Ask questions as if talking to a colleague who knows your entire Salesforce environment.
{% endhint %}

***

## Why Org Genie Exists

Traditional Salesforce data navigation—even within Pharos—requires technical knowledge, time investment, and knowing what you're looking for before you start. Org Genie inverts this paradigm.

### The Challenge with Traditional Data Navigation

While Pharos provides multiple ways to access data (dashboards, custom reports, list views, filters), these approaches have inherent limitations:

{% tabs %}
{% tab title="⏱️ Time Investment" %}
**The Problem:**\
Building reports and dashboards requires significant time investment, which may not be justified for one-time or infrequent queries.

**Example:**\
You need to understand which Issues emerged after last week's deployment. Building a custom report requires:

* Creating filters for date range
* Adding grouping by Issue type
* Setting up sorting by occurrence count
* Formatting the output
* **Total time: 15-30 minutes**

**With Org Genie:**\
Ask: *"Show me Issues created after last Tuesday's deployment, sorted by severity"*

* **Total time: 10 seconds**
  {% endtab %}

{% tab title="🔧 Technical Knowledge Required" %}
**The Problem:**\
Many developers are unfamiliar with Salesforce report building. This is typically a skill area for sales or support teams, not development teams.

**Example:**\
A backend developer joins your team from a Python/Django background. They need to investigate error patterns but don't know:

* How to create Salesforce reports
* Which objects to query
* How to set up filters and groupings

**With Org Genie:**\
Ask questions in plain language. No Salesforce-specific reporting knowledge required.
{% endtab %}

{% tab title="📊 Rigid Interfaces" %}
**The Problem:**\
List views and standard reports have a limited set of operations. They're designed for drilling down into specifics when you know what you're looking for, not for exploratory analysis.

**Example:**\
You notice an error spike and want to understand why. Standard interfaces require you to:

1. Filter by date range
2. Sort by various fields
3. Manually correlate with audit trail
4. Switch between multiple views
5. Manually draw conclusions

**With Org Genie:**\
Ask: *"There's an error spike on January 15th. Were there any metadata changes that could have caused it?"*\
Get correlated analysis immediately.
{% endtab %}

{% tab title="⚙️ Metadata Complexity" %}
**The Problem:**\
Salesforce metadata, especially for complex elements like Flows, is difficult to read and analyze. Even with source control, comparing metadata versions and understanding changes is challenging.

**Example:**\
A Flow was modified last week. Understanding what changed requires:

* Accessing the Flow's metadata XML
* Comparing versions in source control or using Flow version history
* Interpreting complex XML structure
* Understanding the semantic impact of changes

**With Org Genie:**\
Ask: *"Show me changes to the Case Assignment Flow last week"*\
Get a human-readable summary of what changed and why it matters.
{% endtab %}

{% tab title="🔗 Correlation Complexity" %}
**The Problem:**\
Connecting observability data with metadata changes requires manual effort across multiple tools and interfaces. For admins who don't read code, this becomes even more complex.

**Example:**\
Determining if a code change caused an Issue requires:

* Reviewing the Issue's first occurrence time
* Checking Setup Audit Trail around that time
* Manually comparing timestamps
* Analyzing whether the change could cause the error
* **Requires deep technical knowledge**

**With Org Genie:**\
Ask: *"Could any recent changes have caused this Issue?"*\
Get automatic correlation with plain-language explanations.
{% endtab %}
{% endtabs %}

### What Makes Org Genie Different

Org Genie enables you to ask questions you might not even know how to formulate for a traditional report:

**Exploratory Questions:**

* *"What's changed in my org over the last 5 days?"*
* *"What are some problems this change could have caused?"*
* *"Were there any anomalies this week versus last week?"*
* *"Which Issues warrant immediate attention and why?"*

These types of exploratory, context-dependent questions would be extremely difficult or impossible to answer through standard reporting interfaces.

{% hint style="info" %}
**Dashboard Fatigue**

While it's tempting to create dashboards for every possible question, too many visualizations lead to dashboard fatigue—you don't know where to look anymore. Org Genie allows focused, context-specific analysis without cluttering your dashboards.
{% endhint %}

***

## What Determines How Much Org Genie Can Answer

Org Genie is set up from a checklist in Pharos Admin — see [Org Genie Settings](https://docs.pharos.ai/configuration-guide/org-genie-settings.md) for what's required and how to enable each piece. Two of those choices materially change the questions it can answer.

**Change Tracking widens the questions from "what broke" to "what changed."** It periodically pushes your org's metadata to a GitHub repository you control, building a history over time. With it, Org Genie can correlate metadata changes with issue patterns, identify when a specific change was made, and suggest whether a change caused or fixed a problem — answering questions like *"What changed around the time this issue started?"* Without it, Org Genie still queries logs and issues, generates visualizations, identifies patterns, and prioritizes by impact; it simply can't reason about configuration changes.

**History has to accumulate before you can ask about it.** Log and issue indexing completes in about an hour for most orgs, but metadata history only exists from the moment Change Tracking starts running. If you enabled it today, you cannot ask what changed last month — expect to wait one to two weeks before correlation becomes genuinely useful.

***

## How Org Genie Works

### Grounded AI: Data, Not Speculation

Unlike general-purpose AI chatbots (ChatGPT, Claude, etc.), Org Genie is **grounded** in your org's actual data. This means it doesn't generate speculative answers—every response is based on your real observability data and metadata.

**The Process:**

```mermaid
graph TD
    A[1. DATA INDEXING - Continuous<br/>Pharos indexes logs, Issues, metadata into vector database]
    B[2. YOU ASK A QUESTION<br/>Show me errors from last week broken down by category]
    C[3. SEMANTIC SEARCH - Instant<br/>Org Genie finds relevant data matching question intent]
    D[4. CONTEXT-AWARE RESPONSE - 10-15 sec<br/>AI receives question + relevant data, generates response]
    E[5. VISUALIZATION - Optional<br/>Creates charts when requested]
    A --> B --> C --> D --> E
```

{% hint style="success" %}
**No Hallucinations**

Because Org Genie is grounded in your actual data, it doesn't "hallucinate" or make up information. If it doesn't have data to answer your question, it will tell you instead of inventing an answer.
{% endhint %}

### Data Security and Privacy

Your data is stored as a vector index, which provides multiple layers of security:

<table><thead><tr><th width="180">Security Layer</th><th>How It Works</th><th>Protection Level</th></tr></thead><tbody><tr><td><strong>🔢 Vectorization</strong></td><td>Data is transformed into mathematical representations (vectors) rather than stored as raw text</td><td>Extremely difficult to reverse engineer vectors back to original data</td></tr><tr><td><strong>🧩 Chunking</strong></td><td>Data is broken into small chunks before vectorization</td><td>Even if a chunk is reversed, only a tiny subset of data is exposed</td></tr><tr><td><strong>🔒 Practical Irreversibility</strong></td><td>While theoretically possible to reverse vectors, it's practically impossible without massive computational effort</td><td>Industry-standard security for AI-powered systems</td></tr><tr><td><strong>🚫 No Raw Metadata Access</strong></td><td>Pharos stores the vector index but does not have access to your raw metadata in the GitHub repository</td><td>Your source metadata remains under your exclusive control</td></tr></tbody></table>

{% hint style="info" %}
**Your Data Stays Yours**

Pharos processes your data to create searchable indexes, but your raw data remains in your Salesforce org and your controlled GitHub repository. Vector indexes are used for semantic search, not for accessing your actual business information.
{% endhint %}

### Query Process and Performance

When you ask a question, Org Genie follows this process:

1. **Analyze Query** - Understand your natural language question (instant)
2. **Semantic Search** - Find relevant indexed data (1-2 seconds)
3. **Execute Salesforce Queries** - Query logs and Issues objects if needed (2-5 seconds)
4. **AI Processing** - Generate response using large language model (5-10 seconds)
5. **Create Visualizations** - Generate charts if requested (2-3 seconds)

**⏱️ Typical Response Time: 10-15 seconds**

Complex queries over large time ranges may take longer, but most queries complete in under 15 seconds.

### Conversation Context

Org Genie remembers what you asked earlier in the same chat, so follow-up questions build on previous answers.

{% hint style="success" %}
**Context-Aware Follow-Ups**

Org Genie maintains context within a chat session. Follow-up questions are understood in the context of your previous queries in that session, enabling natural, iterative conversations.
{% endhint %}

**Example Conversation:**

```
You: "Show me errors from last week"
Genie: [Returns chart showing 243 errors across 3 categories]

You: "Focus on just the Apex errors"
Genie: [Filters to 87 Apex errors with details]

You: "Which of these are new versus recurring?"
Genie: [Breaks down: 23 new Issues, 64 occurrences of existing Issues]

You: "Show me the top 3 new Issues"
Genie: [Lists top 3 with links and context]
```

**Managing Context:**\
If you want to start a completely new topic, create a new chat to avoid mixing contexts. Each chat session maintains its own conversation history.

***

## Generating Visualizations

Org Genie can generate charts to visualize data, making patterns and trends immediately visible without building dashboards.

### Supported Chart Types

Org Genie supports three chart types, each suited to a different kind of comparison.

<table><thead><tr><th width="150">Chart Type</th><th>Best Used For</th><th>Example Use Case</th></tr></thead><tbody><tr><td><strong>📊 Bar Charts</strong></td><td>Comparing categories or discrete values</td><td>"Show me top 10 affected users in a bar chart"</td></tr><tr><td><strong>📈 Line Charts</strong></td><td>Showing trends over time</td><td>"Plot error frequency over the last month"</td></tr><tr><td><strong>🥧 Pie Charts</strong></td><td>Showing proportions and percentages</td><td>"Generate a pie chart of errors by category"</td></tr></tbody></table>

### Requesting Visualizations

You don't need to specify the exact chart type—Org Genie will choose an appropriate visualization based on your data and question. However, you can request specific types if preferred.

**Flexible Requests:**

* *"Can you show me a chart comparing errors this week versus last week broken down by category?"*
* *"Generate a pie chart showing errors by category for the last 7 days"*
* *"Show me a line chart of all errors over the last month broken down by category"*
* *"Plot the top 10 impacted users in a bar chart"*
* *"Visualize the trend of Flow errors over the last quarter"*

{% hint style="success" %}
**Charts Adapt to Your Question**

Org Genie interprets your intent and creates appropriate visualizations. Asking for "trends over time" will produce line charts; "comparing categories" will produce bar charts—even without explicitly requesting the chart type.
{% endhint %}

### Working with Chart Output

Once a chart is generated, you can expand it, share it, or refine it with follow-up questions.

**Expandable Views:**\
Charts can be expanded to full screen for better visibility and analysis.

**Export and Share:**\
Copy charts into presentations, documentation, or share directly in Slack/Teams channels.

**Iterative Refinement:**\
Ask follow-up questions to adjust visualizations:

* *"Can you show that same data as a bar chart instead?"*
* *"Break that down by user profile"*
* *"Exclude system users from that chart"*

***

## Working with Results

Org Genie provides actionable results designed to integrate seamlessly with your workflow.

### Interactive Elements

Org Genie's responses include interactive elements that connect analysis directly to action.

{% tabs %}
{% tab title="🔗 Direct Links" %}
**Issue References:**\
When Org Genie identifies specific Issues, it returns clickable links directly to the Pharos Issue records.

**Benefit:**\
Seamlessly transition from high-level query to detailed investigation with a single click.

**Example:**

```
You: "Which Issues warrant immediate attention?"
Genie: "Found 3 critical Issues:
        1. [Link] Flow failure affecting 47 users
        2. [Link] Integration timeout with ERP (3x increase)
        3. [Link] Batch job failure blocking data cleanup"
```

Click through to any Issue to investigate further or use issue-level Org Genie for focused analysis.
{% endtab %}

{% tab title="📊 Expandable Charts" %}
**Full-Screen Visualization:**\
Charts can be expanded to full screen for better visibility during analysis or presentation.

**Benefit:**\
Present findings to stakeholders or analyze complex patterns with larger, clearer visualizations.
{% endtab %}

{% tab title="🔄 Iterative Refinement" %}
**Follow-Up Questions:**\
Ask follow-up questions to drill deeper or refine your query based on initial results.

**Benefit:**\
Natural conversation flow allows you to explore data iteratively, adjusting your investigation based on what you learn.

**Example:**

```
You: "Show me errors from last week"
Genie: [Returns 243 errors]

You: "Filter to only errors affecting external users"
Genie: [Returns 87 errors]

You: "Which of those are high severity?"
Genie: [Returns 12 critical errors with details]
```

{% endtab %}

{% tab title="🎯 Start Broad, Then Narrow" %}
**Recommended Approach:**\
Begin with high-level questions to understand overall patterns, then focus on specific areas based on what you learn.

**Benefit:**\
Discover unexpected patterns and avoid confirmation bias by starting with broad exploration.

**Example Workflow:**

```
1. "Show me error trends over the last month"
2. "There's a spike on January 15th—what happened?"
3. "Were there any metadata changes around that date?"
4. "Show me details on the OpportunityTrigger change"
```

{% endtab %}
{% endtabs %}

***

## Best Practices

### When to Use Org Genie vs. Dashboards

Not every question requires Org Genie, and not every dashboard should be replaced. Use the right tool for the right job.

<table><thead><tr><th width="200">Scenario</th><th>Use Org Genie</th><th>Use Dashboards/Reports</th></tr></thead><tbody><tr><td><strong>Frequency</strong></td><td>Ad hoc, one-time queries</td><td>Daily or frequently repeated queries</td></tr><tr><td><strong>Exploration</strong></td><td>When you're not sure what you're looking for</td><td>When monitoring standard metrics regularly</td></tr><tr><td><strong>Complexity</strong></td><td>Questions requiring complex custom reports</td><td>Simple, well-defined metrics</td></tr><tr><td><strong>Correlation</strong></td><td>Connecting metadata changes with observability data</td><td>Viewing observability data alone</td></tr><tr><td><strong>Time Investment</strong></td><td>When you need quick insights without building infrastructure</td><td>When persistence and sharing are important</td></tr><tr><td><strong>Compliance</strong></td><td>Exploratory investigation and troubleshooting</td><td>Audit reporting and compliance requirements</td></tr></tbody></table>

{% hint style="success" %}
**Complementary Tools**

Think of Org Genie and dashboards as complementary, not competing. Use dashboards for consistent monitoring; use Org Genie for investigation and exploration.
{% endhint %}

### Effective Querying Techniques

A few habits produce sharper, more accurate answers.

{% tabs %}
{% tab title="🎯 Be Specific About Time" %}
**Good:**

* *"Last 7 days"*
* *"Between January 10 and January 15"*
* *"This month versus last month"*

**Less Effective:**

* *"Recently"*
* *"A while ago"*
* *"Last week or so"*

**Why it matters:**\
Precise time ranges produce more accurate results and enable better correlation with specific events (deployments, configuration changes).
{% endtab %}

{% tab title="🚫 Exclude Noise" %}
**Good:**

* *"Top 10 impacted users (not system or integration users)"*
* *"Errors affecting external users only"*
* *"Exclude test accounts"*

**Why it matters:**\
Filters out irrelevant data, focusing Org Genie on what matters for your investigation.
{% endtab %}

{% tab title="📊 Start Broad, Then Narrow" %}
**Recommended Flow:**

1. High-level question: *"Show me error trends over the last month"*
2. Identify pattern: Notice spike on January 15
3. Investigate: *"What happened on January 15?"*
4. Correlate: *"Were there any changes around that date?"*
5. Deep-dive: *"Show me details on the OpportunityTrigger change"*

**Why it matters:**\
Avoids premature focus on specific areas; lets data guide your investigation.
{% endtab %}

{% tab title="❓ Ask Why" %}
**Good:**

* *"Why do you think there's a cyclical pattern in this chart?"*
* *"What could explain the spike in Flow errors on January 15?"*
* *"Why would this metadata change cause these errors?"*

**Why it matters:**\
Gets AI insights and explanations, not just data—transforms Org Genie from a query tool into an analytical partner.
{% endtab %}

{% tab title="🔄 Use Follow-Ups" %}
**Example:**

```
You: "Show me Apex errors from last week"
Genie: [Returns 87 errors]

You: "Filter to only high severity"
Genie: [Returns 12 errors]

You: "Which users were affected?"
Genie: [Lists affected users]

You: "Show me the top Issue by occurrence count"
Genie: [Links to specific Issue]
```

**Why it matters:**\
Builds on context from previous responses, creating a natural investigative flow.
{% endtab %}

{% tab title="📈 Request Visualizations" %}
**Good:**

* *"Show me a chart of errors over time"*
* *"Visualize the trend for Flow errors"*
* *"Can you plot that as a bar chart?"*

**Why it matters:**\
Patterns and trends are easier to spot visually than in tables or text. When comparing data or looking for trends, explicitly request charts.
{% endtab %}
{% endtabs %}

### Managing Chat Sessions

Keep your chats organized so context stays intact and your workspace stays uncluttered.

**Create New Chats for Different Topics:**\
Avoid mixing unrelated investigations in the same chat. Keep error spike investigation separate from weekly health check queries.

**Keep Related Questions Together:**\
Maintain context by keeping related questions in one chat session. This allows Org Genie to understand follow-ups without re-explaining context.

**Remove Old Chats:**\
Chats don't auto-delete—clean up your workspace periodically to stay organized and avoid confusion.

**Naming Chats (if supported):**\
Use descriptive names like "Jan 15 Error Spike Investigation" or "Weekly Health Check - Jan 2024" for easy reference.

***

## Usage Contexts: Org-Level vs. Issue-Level

Org Genie can be used in two main contexts, each optimized for different investigation needs.

### Context Comparison

The two contexts differ across several dimensions, from where you access them to how their chat history is stored.

<table><thead><tr><th width="200">Aspect</th><th>Org-Level Queries</th><th>Issue-Level Queries</th></tr></thead><tbody><tr><td><strong>Access Point</strong></td><td>Main navigation menu</td><td>Any Issue detail page</td></tr><tr><td><strong>Scope</strong></td><td>Entire org's logs, Issues, and metadata</td><td>Specific Issue and related context</td></tr><tr><td><strong>Best For</strong></td><td>Exploration, trends, prioritization, health checks</td><td>Deep-dive investigation, root cause analysis, resolution verification</td></tr><tr><td><strong>Chat History</strong></td><td>Per-user (your personal chat history)</td><td>Per-Issue (conversation stored with Issue)</td></tr><tr><td><strong>Example Questions</strong></td><td>"Which Issues warrant attention this week?"</td><td>"What changed that could have caused this Issue?"</td></tr></tbody></table>

### When to Use Each Context

Choose the context that matches your goal—broad exploration or focused investigation.

{% tabs %}
{% tab title="🌐 Org-Level" %}
**Use org-level Org Genie when you want to:**

* Compare multiple Issues across your org
* Analyze trends and patterns over time
* Understand org-wide error patterns
* Prioritize which Issues to investigate first
* Conduct weekly health checks
* Identify anomalies or spikes
* Generate executive-level reports

**Access:**\
Navigate to Org Genie from the main navigation menu.

→ [**Learn more about Org-Level Queries**](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis/org-genie/org-level.md)
{% endtab %}

{% tab title="🔍 Issue-Level" %}
**Use issue-level Org Genie when you want to:**

* Understand why a specific Issue started or stopped
* Identify metadata changes related to a particular error pattern
* Investigate whether a fix actually resolved the Issue
* Determine if an Issue has evolved or split into related Issues
* Correlate deployments with Issue lifecycle events
* Deep-dive into root cause for a single problem

**Access:**\
Open any Issue detail page, then click the Org Genie option.

→ [**Learn more about Issue-Level Queries**](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis/org-genie/issue-level.md)
{% endtab %}
{% endtabs %}

### Navigating Between Contexts

You can move between contexts as your investigation shifts scope.

**Org-Level → Issue-Level:**\
When org-level Org Genie identifies a specific Issue, click the Issue link to view its details, then open issue-level Org Genie for focused investigation.

**Issue-Level → Org-Level:**\
If your Issue-specific investigation reveals a need to understand broader patterns, navigate back to org-level Org Genie.

{% hint style="info" %}
**Context Isolation**

Each context maintains its own chat history, so you won't lose your place in either investigation. Org-level and issue-level conversations are stored separately.
{% endhint %}

***

## Limitations

Understanding Org Genie's limitations helps set appropriate expectations and design effective workflows.

### Query Scope Constraints

Org Genie works with Pharos data and indexed metadata, not your standard business records.

**Can Query:**

* ✅ Pharos logs and Issues objects in Salesforce
* ✅ Indexed metadata from Change Tracking
* ✅ Aggregations and patterns across observability data

**Cannot Query:**

* ❌ Standard Salesforce objects (Account, Contact, Opportunity, etc.)
* ❌ Custom objects unrelated to Pharos
* ❌ Real-time Salesforce configuration (queries historical metadata only)
* ❌ External systems outside Salesforce

### Data Volume Gates

For very large data requests, Org Genie may limit results to maintain performance:

* Large time ranges (e.g., "Show me all errors from the last year") may be summarized
* High-volume queries may return top N results instead of everything
* Org Genie will inform you when results are limited and suggest refinement

### Data Requirements

**You need data to query:**

* Logs must exist for log-related questions
* Issues must be created for Issue-related questions
* Metadata history must accumulate for change correlation
* Change Tracking must be enabled for configuration questions

**Empty results are expected when:**

* You query time periods before Pharos was installed
* Change Tracking was recently enabled (no history yet)
* No errors occurred during the queried time period

### Response Time Variability

Response time depends on query complexity and the volume of data involved.

**Fast Queries (5-10 seconds):**

* Simple questions with narrow time ranges
* Queries hitting indexed data directly
* Visualization requests for small datasets

**Slower Queries (15-30 seconds):**

* Complex questions requiring multiple data sources
* Large time ranges with high data volumes
* Correlation across logs, Issues, and metadata
* Chart generation for complex aggregations

### Context Boundaries

**Context is maintained:**

* ✅ Within a single chat session
* ✅ For follow-up questions in the same conversation

**Context is not maintained:**

* ❌ Across different chat sessions
* ❌ Between org-level and issue-level contexts
* ❌ After creating a new chat

{% hint style="warning" %}
**Governor Limits Apply**

Org Genie queries Salesforce objects, which count toward your org's API limits. However, Pharos is designed to operate well within normal limits for typical usage patterns. Extremely high-frequency queries may impact limits in very small orgs.
{% endhint %}

***

## In This Section

Dive deeper into specific Org Genie contexts:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🌐 Org-Level Queries</strong></td><td>Ask broad questions about your entire org—health checks, trends, and prioritization.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis/org-genie/org-level.md">Org Level</a></td></tr><tr><td><strong>🔍 Issue-Level Queries</strong></td><td>Investigate a specific Issue's root cause, resolution, and related metadata changes.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis/org-genie/issue-level.md">Issue Level</a></td></tr></tbody></table>

***

{% hint style="success" %}
**Start Your First Conversation**

1. Navigate to Org Genie from the main menu (org-level)
2. Ask a simple question: *"Show me errors from yesterday"*
3. Request a visualization: *"Show me a chart of error trends over the last month"*
4. Ask a correlation question: *"Were there any metadata changes last week?"*
5. Click through to a specific Issue and open issue-level Org Genie
6. Ask about that Issue: *"What changed around the time this Issue started?"*

The best way to understand Org Genie is to use it. Start with simple questions and build confidence through experimentation.
{% endhint %}
