Repository map¶
This is the concise contributor-facing map of _codex_. For component details and
status vocabulary, use the repository explanation.
Master overview¶
_codex_ is both a Python ML distribution and an agent-operated engineering
workspace. The repository has four boundaries:
- Implementation:
src/is the canonical home for new Python implementation. - Compatibility and applications: selected root packages are packaging bridges;
cognitive_app/,services/, and infrastructure trees are distinct application or deployment surfaces. - Guidance:
docs/explains architecture, onboarding, and operations. - Operations and governance:
.codex/,.github/workflows/, andscripts/ci/hold state, policy, workflow definitions, and automation.
flowchart LR
R[Repository] --> I[src/ implementation]
R --> C[Compatibility and applications]
R --> D[docs/ guidance]
R --> O[Operational intelligence and governance]
C --> CP[Root package bridges]
C --> APP[cognitive_app/ and services/]
O --> CX[.codex/ state and policy]
O --> GH[.github/workflows/]
O --> SC[scripts/ci/]
Active runtime policy¶
_codex_ is a Python-first platform with a Node.js 22 active runtime layer. The current
implementation policy is: Node.js 22 for all active application manifests and workflow
definitions; historical Node.js 20 references are archival and disabled-only, not active
project policy.
The active sources of truth are the live manifests (package.json, cognitive_app/package.json,
copilot/extension/package.json) and the active workflow definitions under
.github/workflows/. Archive copies under .github/workflow-archive/disabled/ are
historical references, not live runtime requirements.
Core directories¶
| Path | Use it for |
|---|---|
src/codex_ml/ |
ML CLI, data, training, evaluation, inference, serving, and plugins |
src/codex/ |
Ingestion, analysis, transformation, and verification |
src/cognitive_brain/ |
Cognitive contracts, memory, learning, and coordination |
src/rag/ |
Retrieval, embeddings, indexing, and evaluation |
src/mcp/ |
Repository-owned MCP implementation |
configs/ |
Primary Hydra configuration |
tests/ |
Default pytest discovery and regression suites |
cognitive_app/ |
React/TypeScript/Vite dashboard |
Root folders such as training/, tokenization/, and codex_utils/ have explicit
packaging mappings or proxies. Treat them as compatibility/bridge surfaces unless
pyproject.toml identifies them as the active package location.
Operational directories¶
| Path | Use it for |
|---|---|
docs/ |
Current human-facing guidance and architecture |
.codex/ |
Agent policy, session state, memory evidence, and operational records |
.github/workflows/ |
Active GitHub Actions definitions |
scripts/ci/ |
CI checks, orchestration, telemetry, and remediation |
agents/ |
Packaged agent orchestration primitives |
docker/, k8s/, deploy/, infrastructure/ |
Deployment declarations |