# Runtime boundaries

> What this checkout can execute locally versus production Home Mixer, Thunder, and Grox snapshots that depend on unpublished crates.

- Repository: xai-org/x-algorithm
- GitHub: https://github.com/xai-org/x-algorithm
- Human docs: https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c
- Complete Markdown: https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/llms-full.txt

## Source Files

- `README.md`
- `phoenix/pyproject.toml`
- `home-mixer/main.rs`
- `thunder/lib.rs`
- `grox/main.py`
- `candidate-pipeline/lib.rs`
- `LICENSE`

---

---
title: "Runtime boundaries"
description: "What this checkout can execute locally versus production Home Mixer, Thunder, and Grox snapshots that depend on unpublished crates."
---

This checkout is not a buildable For You stack. The only package with a lockfile, installable third-party dependencies, and an entry point that runs offline is `phoenix/` (`pyproject.toml` project name `grok-1`, Python `>=3.11`, `jax==0.8.1`). `home-mixer/`, `thunder/`, `candidate-pipeline/`, and `grox/` are production source snapshots: there is no `Cargo.toml` anywhere in the tree, Grox has no package manifest, and those trees import unpublished `xai_*` crates plus modules that are not present in this repository.

<Warning>
Do not expect `cargo run`, `python grox/main.py`, or a local Home Mixer / Thunder gRPC server to start from this clone. Those binaries need private crates, omitted modules (`crate::params`, `crate::clients`, `thunder::args`, `grox.config`, `grox.service`), and production backends (Kafka, Strato, Gizmoduck, Phoenix inference clusters).
</Warning>

## What runs vs what you can only read

| Surface | Tree | Local execution | What this checkout actually is |
|---|---|---|---|
| Phoenix inference | `phoenix/` | Yes, after Git LFS + unzip | JAX retrieval + ranker with published checkpoints |
| Phoenix unit tests | `phoenix/test_recsys_model.py`, `phoenix/test_recsys_retrieval_model.py` | Yes, no artifacts required | Attention-mask, RoPE, retrieval-tower, and runner assertions |
| Candidate pipeline traits | `candidate-pipeline/` | No | Trait snapshot of `xai_candidate_pipeline` without crate metadata or `component_library` |
| Home Mixer | `home-mixer/` | No | `HomeMixerServer` source; `XService` + proto servers, unpublished clients |
| Thunder | `thunder/` | No | `InNetworkPostsService` + `PostStore` source; missing `args` / `config` / `strato_client` |
| Grox | `grox/` | No | `Engine` / `Dispatcher` / `PlanMaster` source; missing `grox.config`, `grox.service`, `grox.lm` |

```mermaid
flowchart TB
  subgraph local ["Locally executable"]
    PX["phoenix/\nrun_pipeline.py / pytest"]
    LFS["artifacts/oss-phoenix-artifacts.zip\nGit LFS, 2903518802 bytes"]
    PX --> LFS
  end

  subgraph snapshots ["Source snapshots in this checkout"]
    HM["home-mixer/\nHomeMixerServer"]
    TH["thunder/\nThunderServiceImpl"]
    GX["grox/\nEngine + Dispatcher + PlanMaster"]
    CP["candidate-pipeline/\nCandidatePipeline traits"]
  end

  subgraph unpublished ["Not in this repository"]
    CRATES["xai_* crates\nprotos, XServiceBuilder, Kafka, stats"]
    HMOMIT["crate::params, crate::clients, crate::util"]
    THOMIT["args, config, metrics, o2, schema, strato_client"]
    GXOMIT["grox.config, grox.service, grox.lm,\ngrox.prompts, data_types, monitor"]
  end

  subgraph prod ["Production-only backends"]
    KAFKA["Kafka ingest / side effects"]
    STRATO["Strato following lists and stores"]
    GIZ["Gizmoduck, TES, AdIndex, VM ranker"]
    PHXCL["Phoenix prediction cluster / egress sidecar"]
  end

  HM --> CP
  HM --> CRATES
  HM --> HMOMIT
  HM --> prod
  TH --> CRATES
  TH --> THOMIT
  TH --> KAFKA
  TH --> STRATO
  GX --> GXOMIT
  GX --> KAFKA
  GX --> STRATO
```

## Phoenix: the local runtime

`phoenix/` is a self-contained JAX package. `uv.lock` pins Darwin and Linux. `pip` can install the same declared set: `jax`, `jaxlib`, `dm-haiku`, `numpy`. Dev extras add `pytest`.

<Tabs>
<Tab title="uv">

```bash
cd phoenix
uv sync
```

</Tab>
<Tab title="pip">

```bash
cd phoenix
pip install jax jaxlib dm-haiku numpy
```

</Tab>
</Tabs>

### Artifact gate

`.gitattributes` routes `*.zip` and `*.npz` through Git LFS. Until `git lfs pull`, `phoenix/artifacts/oss-phoenix-artifacts.zip` is a 135-byte pointer (`oid sha256:fbc6017d00588754e22e0c7eb2f786a008a74d309c03c8085fa2fad418a83dac`, size `2903518802`). `run_pipeline.py` will not load models from that stub.

<Steps>
<Step title="Materialize the archive">
Pull LFS objects, then extract next to the pointer:

```bash
git lfs pull
cd phoenix
unzip artifacts/oss-phoenix-artifacts.zip -d artifacts/
```
</Step>
<Step title="Confirm the extract layout">
`run_pipeline.py` opens these paths relative to `--artifacts_dir` (default `./artifacts`):

:::files
artifacts/oss-phoenix-artifacts/
  retrieval/
    model_params.npz
    embedding_tables.npz
    config.json
  ranker/
    model_params.npz
    embedding_tables.npz
    config.json
  sports_corpus.npz
  example_sequence.json
:::
</Step>
<Step title="Run inference">

```bash
uv run run_pipeline.py --artifacts_dir artifacts/oss-phoenix-artifacts
```
</Step>
<Step title="Verify">
Success is a `PIPELINE RESULTS — User <id>` table with columns `Rank`, `Score`, `Ret`, `Fav`, `Reply`, `RT`, `Dwell`, `VQV`, `Topics`, and `https://x.com/a/status/<post_id>` URLs, plus a `Weighted score range:` footer. Failure at this step is almost always an LFS pointer, a wrong `--artifacts_dir`, or a missing `retrieval/config.json`.
</Step>
</Steps>

<ParamField body="--artifacts_dir" type="path" default="./artifacts">
Directory that contains `retrieval/`, `ranker/`, and (unless overridden) the sequence and corpus files.
</ParamField>

<ParamField body="--sequence_file" type="path">
User history JSON. Default: `<artifacts_dir>/example_sequence.json`.
</ParamField>

<ParamField body="--corpus_file" type="path">
Precomputed candidate NPZ (`post_ids`, `candidate_representations`, `author_ids`, optional `topics`). Default: `<artifacts_dir>/sports_corpus.npz`.
</ParamField>

<ParamField body="--top_k_retrieval" type="int" default="200">
Dot-product retrieval depth against the sports corpus.
</ParamField>

<ParamField body="--top_k_display" type="int" default="30">
How many ranked rows to print.
</ParamField>

Local ranking is a demo weighted sum, not Home Mixer `WeightedScorer` / `RankingScorer` tables:

```text
score = P(fav)*1.0 + P(reply)*0.5 + P(rt)*0.3 + P(dwell)*0.2
```

`run_ranker.py` and `run_retrieval.py` still exist. They construct synthetic `create_example_batch` / `create_example_corpus` tensors and do **not** load the published archive. The production-shaped local path is `run_pipeline.py`.

### Tests that do not need checkpoints

```bash
cd phoenix
uv run pytest test_recsys_model.py test_recsys_retrieval_model.py
```

These modules assert `make_recsys_attn_mask` isolation, right-anchored RoPE, post-age buckets, candidate-tower normalization, and retrieval `top_k`. They are the second local success signal after the ranked table.

<Info>
The published checkpoint is a frozen mini Phoenix snapshot and a sports-only corpus (`sports_corpus.npz`, on the order of 537K posts). Production Phoenix is a larger, continuously trained model scored over a live global corpus through `PhoenixScorer` cluster / egress clients. Matching `config.json` keys is not the same as matching production capacity.
</Info>

## Home Mixer: source snapshot, not a binary

`home-mixer/main.rs` defines a `HomeMixer gRPC Server` clap surface and boots `XServiceBuilder::new("home-mixer")`. That is production wiring, not something this clone can link.

| Flag | Default in source | Role |
|---|---|---|
| `--grpc_port` | `50051` | gRPC listen port |
| `--metrics_port` | `9090` | Metrics port |
| `--shard_coordinate` | `-1` | `< 0` means no `ShardCoordinate` |
| `--shard_total_size` | `500` | Used only when `shard_coordinate >= 0` |
| `--datacenter` | `atla` | Passed into `XServiceBuilder` and `PhoenixCandidatePipeline::prod` |
| `--otel_endpoint` | `""` | OpenTelemetry endpoint |

`main` also requires unpublished bootstrap files and env:

- `xai_stringcenter::init_from_file(params::STRINGCENTER_BUNDLE_PATH)`
- `.with_featureswitches(params::FS_PATH, true)`
- `.with_decider(params::decider_path(), None)`
- `.with_tls(TlsMode::server_mtls_from_env()?)`
- `RejectDarkTrafficLayer` / `dark_traffic_setup`
- `xai_profiling::profiling_router()`

`HomeMixerServer` implements `xai_x_service_builder::XService`. `build` constructs `ProdGizmoduckClient` (`"home-mixer.prod"`), `PhoenixCandidatePipeline::prod(shard_coordinate, datacenter)`, `ScoredPostsServer`, and `ForYouCandidatePipeline`. `register` attaches:

- `ScoredPostsServiceServer`
- `ForYouFeedServiceServer`

Gzip and Zstd compression are enabled. Message size limits come from `params::MAX_GRPC_MESSAGE_SIZE` (module not in tree).

### Omitted Home Mixer modules

`home-mixer/lib.rs` exports `ads`, `candidate_pipeline`, `models`, `scorers`, `server`. It does **not** declare the modules the rest of the crate uses:

| Missing path | Used for |
|---|---|
| `crate::params` | `TEST_USER_IDS`, `STRINGCENTER_BUNDLE_PATH`, `FS_PATH`, scorer weights, source enable flags, blender positions |
| `crate::clients` | Gizmoduck, TES, Strato, AdIndex, Kafka publishers, VM ranker, served history, S2S cert paths |
| `crate::util` | URT helpers (`for_you_server.rs` imports `crate::util::urt`) |

`PhoenixCandidatePipeline::prod` also reaches `xai_candidate_pipeline::component_library::clients` (Phoenix retrieval / prediction). That `component_library` tree is not in `candidate-pipeline/` here.

### Request gates that exist only in this source

`QueryBuilder::build` rejects `viewer_id == 0` with `Status::invalid_argument("viewer_id must be specified")`.

`ScoredPostsServer::run_pipeline` and `ForYouFeedServer::get_for_you_feed` short-circuit when `params::TEST_USER_IDS` contains the user: empty `scored_posts` / `items` and `PipelineResult::empty()`. You cannot evaluate that set locally because `params` is unpublished.

Phoenix sources (`PhoenixSource`, `PhoenixMOESource`, `PhoenixTopicsSource`) return `"missing retrieval_sequence"` when `ScoredPostsQuery.retrieval_sequence` is `None`. That is production query-hydration failure, not a local CLI error.

## Thunder: in-network store without a crate

`thunder/main.rs` parses `args::Args`, builds `PostStore` + `StratoClient` + `ThunderServiceImpl`, wraps the gRPC service in `xai_http_server::HttpServer`, optionally starts `xai_profiling::spawn_server(3000, ...)`, then calls `kafka_utils::start_kafka`.

`thunder/lib.rs` declares modules that are absent from the snapshot:

| Missing module | Callers |
|---|---|
| `args` | `main.rs`, `kafka_utils.rs` (`Args::parse`, Kafka/SASL fields) |
| `config` | `thunder_service.rs` (`MAX_INPUT_LIST_SIZE`, `MAX_POSTS_TO_RETURN`, `MAX_VIDEOS_TO_RETURN`) |
| `metrics` | `thunder_service.rs` histograms / in-flight gauges |
| `o2` | declared in `lib.rs` only |
| `schema` | declared in `lib.rs` only |
| `strato_client` | `StratoClient::new` / `fetch_following_list` |

Fields read from the missing `Args` type include `post_retention_seconds`, `request_timeout_ms`, `max_concurrent_requests`, `grpc_port`, `http_port`, `enable_profiling`, `kafka_num_threads`, `is_serving`, and Kafka/SASL settings (`security_protocol`, `sasl_*`, `kafka_group_id`, `auto_offset_reset`, `fetch_timeout_ms`, `skip_to_latest`, `in_network_events_consumer_dest`). Defaults are not in this checkout.

Kafka topic constants in `thunder/kafka_utils.rs` are empty strings (`TWEET_EVENT_TOPIC`, `TWEET_EVENT_DEST`, `IN_NETWORK_EVENTS_TOPIC`, `IN_NETWORK_EVENTS_DEST`). SASL password env lookups use `std::env::var("")`. Those are redacted production hooks, not a local broker config.

`GetInNetworkPosts` acquires a semaphore with `try_acquire`. At capacity it returns:

```text
Status::resource_exhausted("Server at capacity, please retry")
```

An empty `following_user_ids` list falls back to `StratoClient::fetch_following_list`. Neither the semaphore path nor Strato can be exercised without the missing modules and unpublished `xai_thunder_proto` / `xai_kafka` / `xai_wily` crates.

## Grox: plan engine without a service package

`grox/main.py` is a production process: `init_proc("main")`, then `Engine`, `Dispatcher`, and `GrpcServer` start, wait on SIGINT/SIGTERM, sleep 300 seconds, then stop. There is no `grox/pyproject.toml` or `requirements.txt`.

Immediate import failures from this tree:

```text
from grox.service import GrpcServer          # no grox/service
from grox.config.config import grox_config  # no grox/config
```

`Engine` and `Dispatcher` additionally import `monitor.logging`, `monitor.metrics`, `grox.data_loaders.media_processor`, and `grox.data_loaders.data_types`. Classifiers and embedders import `grox.lm.*` and `grox.prompts.template`.

Present in-tree (readable, not independently runnable):

- `PlanMaster.ALL_PLANS`: `PlanInitialBanger`, `PlanPostSafety`, `PlanSpamComment`, `PlanPostEmbeddingWithSummary`, `PlanPostEmbeddingWithSummaryForReply`, `PlanPostEmbeddingV5`, `PlanPostEmbeddingV5ForReply`, `PlanReplyRanking`, `PlanSafetyPtos`
- Per-plan `TASK_DEPENDENCIES` DAGs
- `Dispatcher` stream generators (post, safety, embedding v5, PTOS, recovery)

`python grox/main.py` fails at import before any plan runs.

## Candidate pipeline crate vs this folder

`candidate-pipeline/` is the public trait surface: `Source`, `Hydrator`, `Filter`, `Scorer`, `Selector`, `QueryHydrator`, `SideEffect`, and `CandidatePipeline::execute` (query hydrate → sources → hydrate → filter → score → select → post-select → side effects).

That folder still cannot compile here:

- No `Cargo.toml`
- `PipelineQuery` requires `xai_feature_switches::Params` and `xai_decider::Decider`
- Every stage uses `xai_stats_macro::receive_stats` and `xai_stats_receiver`

Home Mixer does not path-depend on this directory. It imports the unpublished crate `xai_candidate_pipeline`, including `component_library` clients and caches that are **not** in the snapshot (`MokaCache`, `PhoenixPredictionClient`, `PhoenixRetrievalClient`, `SocialGraphClientOps`, `StratoClient`). Treat `candidate-pipeline/` as documentation of the stage contracts, not as a drop-in crate.

## Unpublished `xai_*` crates referenced by the snapshots

These identifiers appear in Rust `use` paths and do not exist in this repository or on a public registry path in-tree:

| Crate | Typical consumer |
|---|---|
| `xai_home_mixer`, `xai_home_mixer_proto` | `home-mixer/main.rs`, servers, models |
| `xai_candidate_pipeline` | Home Mixer pipelines and components |
| `xai_x_service_builder`, `xai_x_rpc`, `xai_dark_traffic` | Home Mixer process bootstrap |
| `xai_stringcenter`, `xai_feature_switches`, `xai_decider` | Params / FS / decider |
| `xai_http_server`, `xai_thunder_proto`, `xai_kafka`, `xai_wily` | Thunder process + ingest |
| `xai_stats_macro`, `xai_stats_receiver`, `xai_profiling` | All Rust snapshots |
| `xai_recsys_proto`, `xai_visibility_filtering`, `xai_strato` | Scoring, VF, stores |
| `xai_safety_label_store`, `xai_manhattan`, `xai_redis_client` | Brand safety, cache, stores |
| `xai_pipeline_tracing`, `xai_urt_thrift`, `xai_x_thrift` | Tracing and response mapping |
| `xai_recsys_aggregation`, `xai_recsys_logging_thrift`, `xai_uas_thrift` | Sequence / logging |
| `xai_ads_injection_proto`, `xai_account_recommendations_mixer_proto`, `xai_prompts_thrift`, `xai_vm_ranker_proto` | Ads, WTF, prompts, VM ranker |
| `xai_twittercontext_proto`, `xai_geo_ip`, `xai_core_entities`, `xai_post_text` | Viewer / geo / entities |

Apache-2.0 in `LICENSE` covers the published files. It does not ship those crates.

## Production backends the snapshots assume

Even with the missing modules restored, the Rust and Grox snapshots are not offline:

| Backend | Snapshot use |
|---|---|
| Kafka | Thunder tweet / in-network ingest; Home Mixer side effects (`publish_seen_ids`, reranking, client events); Grox stream generators |
| Strato | Thunder following-list fallback; Home Mixer hydrators; Grox `TweetStratoLoader` |
| Gizmoduck | `ProdGizmoduckClient` in `HomeMixerServer::build` |
| Phoenix prediction / retrieval gRPC | `PhoenixScorer` cluster + egress; `PhoenixSource` / MoE / topics |
| Feature switches + decider + String Center | `XServiceBuilder` and every `query.params.get(...)` |
| mTLS / S2S certs | `TlsMode::server_mtls_from_env`, `S2S_CHAIN_PATH` / `S2S_CRT_PATH` / `S2S_KEY_PATH` |
| TES, AdIndex, VM ranker, served-history, Redis | Candidate hydration, ads, ranking, cache side effects |

Local Phoenix replaces that entire serving path with `sports_corpus.npz` dot products and in-process Haiku `apply`.

## Failure signals by surface

| Symptom | Meaning |
|---|---|
| `oss-phoenix-artifacts.zip` is ~135 bytes of `version https://git-lfs.github.com/spec/v1` | LFS pointer not pulled |
| `FileNotFoundError` for `retrieval/config.json` | Archive not extracted, or `--artifacts_dir` points at the zip parent without `oss-phoenix-artifacts/` |
| Ranked table prints | Local Phoenix pipeline succeeded |
| `uv run pytest …` green | Mask / retrieval unit tests succeeded; not a production parity check |
| No `Cargo.toml` / unresolved `xai_*` | Expected. Rust snapshots are not a workspace |
| `ModuleNotFoundError: grox.service` / `grox.config` / `monitor` | Expected. Grox process modules were not published |
| `viewer_id must be specified` | Home Mixer source behavior when `viewer_id == 0` |
| Empty feed for some user ids | `TEST_USER_IDS` short-circuit in source |
| `PhoenixSource: missing retrieval_sequence` | Query hydrator did not fill `ScoredPostsQuery` |
| `Server at capacity, please retry` | Thunder semaphore `RESOURCE_EXHAUSTED` |

<Check>
If the goal is to exercise the published algorithm, stay in `phoenix/`: LFS pull, unzip, `uv run run_pipeline.py`, then `uv run pytest`. Use the Home Mixer, Thunder, and Grox trees as architecture references for how production composes those models, not as local services.
</Check>

## License and reuse

Published files are Apache License 2.0 (`LICENSE`). You can run, modify, and redistribute the Phoenix package and the snapshot sources under that license. You cannot obtain the unpublished `xai_*` crates, proto crates, or omitted Grox/Home Mixer/Thunder modules from this repository.

## Next

<CardGroup>
<Card title="Installation" href="/installation">
Python 3.11+, uv or pip, Git LFS, and the extract layout required before inference.
</Card>
<Card title="Quickstart" href="/quickstart">
Extract `oss-phoenix-artifacts` and recognize the ranked table as the success signal.
</Card>
<Card title="Run the inference pipeline" href="/run-inference-pipeline">
Load retrieval and ranker checkpoints, encode `example_sequence.json`, retrieve from `sports_corpus.npz`.
</Card>
<Card title="Assemble a Home Mixer request" href="/assemble-home-mixer-request">
CLI flags, `QueryBuilder.viewer_id` validation, and For You versus ScoredPosts entry points in source.
</Card>
<Card title="Execute Grox content plans" href="/execute-grox-plans">
Engine, Dispatcher, and `PlanMaster` fan-out as written — not as a local server.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
LFS pointer failures, empty `TEST_USER_IDS` feeds, Thunder `RESOURCE_EXHAUSTED`, unpublished Grox modules.
</Card>
</CardGroup>