---
name: intrinsic-core-bazel
description: Guides agents in configuring hermetic Bazel Bzlmod dependencies, managing third-party PyPI packages via rules_python, importing Intrinsic SDK libraries and protobufs, and discovering SDK APIs in the Bazel sandbox.
Triggers: configure Bazel dependencies, add PyPI package, import Intrinsic SDK, discover SDK APIs, resolve Bzlmod modules, fix missing @ai_intrinsic_sdks.
Subsystems: Bazel, Bzlmod, rules_python, ai_intrinsic_sdks, pip-compile.
---

# Bazel dependency management and SDK discovery in Intrinsic Core

When developing Intrinsic Core skills, services, and applications, all software dependencies (intra-workspace reusable libraries, first-party Intrinsic SDK libraries/protobufs, and external third-party PyPI packages) must be hermetically declared and managed through Bazel 8+ Bzlmod (`MODULE.bazel`).

## Workspace initialization with inctl bazel init

When setting up a new evaluation or service workspace, run the canonical initialization command:
```bash
inctl bazel init
```
This scaffolds the root `MODULE.bazel` and `.bazelrc` configuration files.

### Configuration flags and standard `bazel` execution

Due to a current bug, you need to change the `.bazelrc` generated by the `inctl bazel init`:

- **Omit monorepo config flags**: The standalone workspace `.bazelrc` defines local optimization and repository flags; omit monorepo-specific config flags to prevent undefined config errors.
- **Clean local compilation flags**: Ensure clean local compilation flags in `.bazelrc`:
  ```ini
  common -c opt
  common --remote_upload_local_results=false
  common --repo_env=DO_NOT_TRACK=1
  common --experimental_repository_cache_hardlinks
  ```

## Progressive disclosure reference hub

Read the specialized reference guide under `references/` before modifying dependencies or investigating build failures:

| Reference guide | Technical scope and focus | When to read it |
| :--- | :--- | :--- |
| [references/sdk-dependencies-and-imports.md](references/sdk-dependencies-and-imports.md) | Canonical SDK target mapping table, protobuf naming conventions (`_py_pb2` vs `_py_pb2_grpc`), SDK discovery in output base, and scoped `bazel query` commands. | Adding Intrinsic SDK dependencies, importing proto messages, or discovering available SDK interfaces. |
| [references/pypi-and-rules-python.md](references/pypi-and-rules-python.md) | Four-stage PyPI lifecycle (`requirements.in`, `compile_pip_requirements`, `requirements_lock.txt`, `@pypi_deps//<pkg>:pkg`), hermetic Python 3.11 toolchain, and intra-workspace code sharing. | Adding external Python packages (e.g. NumPy, SciPy, OpenCV) or sharing libraries across targets. |
| [../intrinsic-core-debugging/references/bazel.md](../intrinsic-core-debugging/references/bazel.md) | Constitutional circuit breaker rules, input-aware diagnostic decision tree, and dynamic linker ABI resolution. | Build compilation failures, lockfile synchronization errors, or missing repository errors. |

## 1. Hermetic toolchain vs. host interpreter alignment

The workspace dependency graph is governed strictly by declarative Bazel configuration:
- Register the hermetic toolchain via `rules_python` (`python.toolchain(python_version = "3.11")` / `py_runtime_pair`); never invoke host `/usr/bin/python3`.
- Model every dependency hermetically; do not assume packages or tools exist on the host filesystem.

## 2. System site-packages vs. offline wheel cache

In Intrinsic Core workspaces, isolation from host Python environments is mandatory:
- Never point `PYTHONPATH` to `/usr/lib/python3/dist-packages` or system directories.
- Never inject `PIP_FIND_LINKS=/var/cache/pip_cache` or scrape `/var/cache/pip_cache` for `.whl` files.
- Never create local in-tree `intrinsic/` mock stubs.

## 3. Offline wheel discovery and deduplication

Manage external dependencies (e.g. `numpy`, `scipy`, `flask`) deterministically:
- Declare abstract requirements in `requirements.in` and compile to `requirements_lock.txt` via `bazel run //:requirements.update`.
- Lockfile deduplication and transitive pinning are handled hermetically by `rules_python`.

## Pre-execution System 2 reflection checklist

Before modifying `MODULE.bazel`, editing `requirements.in`, or authoring `BUILD` rules, run this self-critique:
- [ ] Has `inctl bazel init` been executed to scaffold the workspace?
- [ ] Is every dependency modeled hermetically in Bazel rather than assumed to exist on the host filesystem?
- [ ] Are third-party packages declared in `requirements.in` and compiled to `requirements_lock.txt` via `bazel run //:requirements.update`?
- [ ] Are intra-workspace libraries declared as `py_library` targets with public visibility?
- [ ] Are Intrinsic SDK dependencies declared under `@ai_intrinsic_sdks//intrinsic/<domain>/...` and imported via `from intrinsic.<domain> import ...`?
- [ ] Are Python proto targets declared with exact `<name>_py_pb2` (or `<name>_py_pb2_grpc`) naming?

## Paired safety guardrails

1. **Hermetic toolchain governance**: Declare all module dependencies in `MODULE.bazel` and register the hermetic Python 3.11 toolchain via `rules_python`; do not rely on host system Python (`/usr/bin/python3`) or manual `pip install`.
2. **Offline wheel isolation**: Declare third-party packages in `requirements.in` and compile them using `bazel run //:requirements.update`; do not scrape `/var/cache/pip_cache` or inject `PIP_FIND_LINKS`.
3. **Runtime environment hygiene**: Import external packages exclusively through Bazel target dependencies; do not set `PYTHONPATH` to point to `/usr/lib/python3/dist-packages` or host system directories.
4. **SDK import integrity**: Import all first-party capabilities from `@ai_intrinsic_sdks` using canonical module paths; do not author in-tree mock directories (`intrinsic/`) or fallback classes.
5. **Anti-thrashing modification cap**: Follow the diagnostic decision tree in `intrinsic-core-debugging/references/bazel.md` when encountering build issues; do not exceed 2 consecutive failed build attempts without diagnosing root cause.

## Verification criteria

- [ ] `MODULE.bazel` declares `ai_intrinsic_sdks` and `rules_python` with `pip.parse`.
- [ ] All required third-party packages are declared in `requirements.in` and pinned in `requirements_lock.txt`.
- [ ] Intra-workspace shared libraries are declared as `py_library` rules with public visibility.
- [ ] All Intrinsic SDK dependencies reference canonical `@ai_intrinsic_sdks` targets.
- [ ] All targets compile and pass tests cleanly using `bazel test //...`.