atlas-optimization-patterns
Skill2 starsChanged 5 months agoApache-2.0View on GitHub
Aggressive optimization patterns for atlas. Overrides standard Python defaults with zero-dep, startup-time, and memory-efficient alternatives. Honed for a project that runs a read-only parquet-backed RAG bundle loaded into numpy at startup and queried via MCP. Use when making any code change — these patterns take precedence over generic Python best practices.
In this repository16 other files it gives its agents.
- architecture-decision-recordsSkill
- atlas-add-toolSkill
- atlas-build-bundleSkill
- atlas-ci-releaseSkill
- atlas-rag-evaluationSkill
- embedding-strategiesSkill
- hybrid-search-implementationSkill
- mcp-builderSkill
- python-code-styleSkill
- python-observabilitySkill
- python-resilienceSkill
- python-testing-patternsSkill
- python-type-safetySkill
- readme-maintenanceSkill
- skill-creatorSkill
- uv-package-managerSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Zero new deps: Every library adds import time, CVE surface, and lockfile bloat.
- Very specific: line 35
C-level string ops when possible: Use pyarrow.compute (match_substring) instead of Python loops over 250k strings.
- Very specific: line 37
Use pc.match_substring(arrow_array, token) — it's the same speed as pandas str.contains.
- Very specific: line 43
Only for onnx-cpu backend — MLX and CUDA are sequential.
- Very specific: line 45
Lazy init for argparse and other I/O: Never call parse_args() or read_parquet() at module level.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
When to use
- Adding a new dependency — always ask "can I do this with numpy/pyarrow?"
- Choosing a data structure for the chunks table
- Writing startup/import-heavy code
- Adding CPU-bound parallel work
- Any change to
atlas/source files
Principles
- Zero new deps. Every library adds import time, CVE surface, and lockfile bloat. Prefer numpy + pyarrow (already installed) over anything new. Pandas is explicitly banned — see patterns below.
- Optimize startup, not just hot path. A ~300 ms pandas import
on every
atlas-*command hurts more than a 10 ms saving in a rarely-hit code path. - DataFrame abstractions are overhead. The chunks table is
read-only, loaded once, and accessed by column. Store columns as
numpy arraysfor masks andlist[str]for string data. Index by position, not by label. - C-level string ops when possible. Use
pyarrow.compute(match_substring) instead of Python loops over 250k strings. Usepc.match_substring(arrow_array, token)— it's the same speed as pandasstr.contains. - Process-level parallelism for CPU-bound ONNX. ONNX session.run
is CPU-bound. Use
concurrent.futures.ProcessPoolExecutorwithmin(os.cpu_count(), 4)workers, each loading its own ONNX session. Only foronnx-cpubackend — MLX and CUDA are sequential. - Lazy init for argparse and other I/O. Never call
parse_args()orread_parquet()at module level. Use the_get_args()/_bundle_cachedouble-checked locking pattern fromrag_server.py. - Pre-compute at build time. Norms, manifest SHAs, anything that can be computed once and stored. Query time should be as close to a single matrix multiply as possible.
- Single matrix multiply for cosine similarity. 250k × 768 dims:
(embeddings @ query).flatten() / norms. No FAISS, no Qdrant, no vector database. Numpy is sufficient and has zero infrastructure. - Don't rebuild what's already built. The bundle is the slowest
thing we produce (~15 min MLX, hours on CPU). Default to publishing
the existing
./data/rag-bundle. Only rebuild when the docs source has changed. This is encoded inscripts/publish-bundle.sh.
Banned dependencies
pandas— replaced bypyarrow+numpy. Seeatlas/make_bundle.pybuild_chunk_table()andatlas/rag_server.pyBundle.__init__()for the patterns.faiss/qdrant/chromadb— numpy matmul suffices for 250k vectors. Only reconsider at 10M+ chunks or if live updates are needed.joblib—concurrent.futuresis stdlib and sufficient.
Recommended patterns
Parquet read → numpy columns
table = pq.read_table(path)
pubs = table.column("publication").to_numpy(zero_copy_only=False)
ids = table.column("id").to_pylist()
texts = table.column("text").to_pylist()
id_map = {cid: i for i, cid in enumerate(ids)}String contains over arrow array
matches = pc.match_substring(title_col, token) # returns bool array
boost = matches.cast("float32").to_numpy()Build parquet from lists (no DataFrame)
cols: dict[str, list] = {"col_a": [], "col_b": []}
# ... fill cols ...
table = pa.table(cols)
pq.write_table(table, path)Parallel ONNX embedding
def _embed_shard(model_id, prefer, texts, batch_size):
embedder = get_embedder(model_id, prefer=prefer)
return embedder.embed_with_progress(texts, batch_size=batch_size, show_progress=False)
with ProcessPoolExecutor(max_workers=n_workers) as pool:
futures = {pool.submit(_embed_shard, ...): i for i, shard in enumerate(shards)}
for f in as_completed(futures):
results[futures[f]] = f.result()Double-checked locking for singletons
_instance: Bundle | None = None
_lock = asyncio.Lock()
async def get_bundle() -> Bundle:
global _instance
if _instance is not None:
return _instance
async with _lock:
if _instance is not None:
return _instance
_instance = Bundle(path)
return _instanceDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

