> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gildea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scope context

> Define the territory you track: the themes and entities every later step operates over.

**Scope** your territory before you chase anything. Which entities and themes actually matter to your question is rarely obvious up front, and pinning it down by hand means days of reading around to learn who is moving and where the conversation sits. Gildea makes it a few calls. A live theme map shows the market's structure and its momentum, faceted entity navigation surfaces who is rising and who is fading, and a full profile on any entity anchors your scope to real, tracked data. The output is your **territory**: the themes and entities every later step searches, monitors, and verifies against.

## The recipe

Scoping is pure navigation over Gildea's structured layer, with no model calls. You read the theme map, facet the entity space down to the ones you care about, profile your central entity, then lock the result into a `scope` the other recipes reuse.

<Steps>
  <Step title="Map the market">
    Pull the theme vocabulary. Themes sit on two axes: `value_chain` (the structural layers, from infrastructure up to applications) and `market_force` (the dynamics acting on them). Each carries weekly momentum, so you see what is heating up and what is cooling. See [Themes](/concepts/themes).
  </Step>

  <Step title="Facet the entities">
    `entities.list` exposes nine facets (`type`, `theme`, `scale`, `direction`, `confidence`, `stability`, `notability`, `name`) plus `sort`. Slice the entity space down to your territory, and contrast who is rising against who is declining. See [Entities](/concepts/entities).
  </Step>

  <Step title="Profile your central entity">
    `entities.get` returns the full picture for one entity: its trend and reach, where it operates across the value chain, the market forces touching it, and the entities it is most discussed alongside.
  </Step>

  <Step title="Lock the scope">
    Combine the themes, entities, and a time window into the territory every later recipe operates over.
  </Step>
</Steps>

Install `gildea`, set `GILDEA_API_KEY`, then (pure SDK, no model calls):

```python theme={null}
from gildea import Gildea

gildea = Gildea()

# 1. The market map: themes sit on two axes -- value_chain (structural layers,
#    infra -> apps) and market_force (the dynamics on them). Each carries momentum.
themes = gildea.themes.list()["themes"]

def by_axis(axis):
    rows = [t for t in themes if t["axis"] == axis]
    return sorted(rows, key=lambda t: t["signal_count"], reverse=True)

for axis in ("value_chain", "market_force"):
    print(f"\n{axis}:")
    for t in by_axis(axis):
        delta = t["trend"]["current_week"] - t["trend"]["prior_week"]
        print(f"  {t['label']:26} {t['signal_count']:>4} signals  "
              f"{t['direction'] or '-':9} wk {delta:+d}")

# Anchor your territory on the busiest structural theme.
theme = by_axis("value_chain")[0]["label"]

# 2. Faceted entity navigation: nine facets + sort. Contrast two slices.
def orgs(theme, **facets):
    return gildea.entities.list(
        theme=theme, type="organization", sort="trend", limit=50, **facets
    )["entities"]

rising = orgs(theme, direction="Rising")
declining = orgs(theme, direction="Declining", notability="High")
print(f"\nIn '{theme}': {len(rising)} rising / {len(orgs(theme))} total orgs")
print("  rising:   ", ", ".join(e["name"] for e in rising[:6]) or "(none this week)")
print("  declining:", ", ".join(e["name"] for e in declining[:6]))

# 3. Central entity profile: the full intelligence picture for one entity.
e = gildea.entities.get("NVIDIA")
tr = e["trend"]
print(f"\n{e['name']} ({e['entity_id']}) -- {e['type']}, scale={e['scale']}, "
      f"{e['direction']}, notability={e['notability']}")
print(f"  reach: share_of_voice={tr['share_of_voice']:.0%}, "
      f"{tr['source_diversity']} distinct sources, wk {tr['current_week']} vs {tr['prior_week']}")

def top(dist, n=3):
    return ", ".join(f"{k} ({v})" for k, v in sorted(dist.items(), key=lambda x: -x[1])[:n])

print(f"  operates in: {top(e['value_chain_distribution'])}")
print(f"  forces:      {top(e['market_force_distribution'])}")
mix = e["content_type_mix"]
print(f"  coverage:    {mix.get('event', 0)} events / {mix.get('analysis', 0)} analyses")
print(f"  alongside:   {', '.join(r['name'] for r in e['related_entities'][:6])}")

# 4. Lock the scope: themes + entities + window = the territory every later
#    recipe (search, update, verify, embed) operates over.
scope = {
    "themes": [theme],
    "entities": [e["entity_id"]] + [r["entity_id"] for r in e["related_entities"][:5]],
    "window": "90d",
}
print(f"\nscope locked: {len(scope['entities'])} entities, theme '{theme}', window {scope['window']}")
```

## What you get

Your **territory**: the themes that frame the question, the entities worth tracking within them, and a profile of your central entity, every field from real tracked data. It is a plain object the rest of the loop reuses. [Search](/guides/search) pulls verified signals across it, [Update](/guides/update) keeps it current, [Verify](/guides/verify) traces any unit back to its source, and [Embed](/guides/embed) stores it beside your own data. Because scope is built from live theme and entity intelligence, re-running it re-checks who is moving before you commit.

<CardGroup cols={3}>
  <Card title="List themes" icon="tags" href="/api-reference/themes/list" />

  <Card title="Get entity" icon="building" href="/api-reference/entities/get" />

  <Card title="Search for signals" icon="magnifying-glass" href="/guides/search" />
</CardGroup>