Nylo

Imported from DeeKush/Nylo (AGENTS.md). Install upstream with npx skills add DeeKush/Nylo. Copyright stays with the author.

Nylo — Rules for AI assistants working in this repo

Read this before writing code here. It exists because four people will likely have AI assistants generating code in parallel this weekend, and the fastest way to lose a day is for one of those assistants to "fix" something back to a wrong-but-intuitive default that was already deliberately corrected once. Background/rationale for every rule below lives in docs/DECISIONS.md — read that before overriding any of them, not after.

Hard constraints

1. Python only, for every Lambda. No Node/TypeScript/Go Lambdas, ever, regardless of what's convenient for a given integration. One language across four people's parallel work is a deliberate scope decision, not an oversight.

2. ProcessedReels and UserReelLinks are two separate DynamoDB tables and must stay that way. ProcessedReels is a global, shared cache of what a reel is (summary, transcript, caption, category, embedding reference, processing lock status) — it contains no user identity. UserReelLinks is the only table that maps igsid -> media_id and is the only source of truth for "who saved what." Every search, browse, or ask query is scoped through UserReelLinks first. Do not merge these tables, do not add a user field to ProcessedReels, and do not let any handler read reel content without first checking ownership through UserReelLinks. See docs/DATA_MODEL.md.

3. Cedar authorizes actions. It does not filter results. Cedar's policies (SearchReels, ViewLibrary, AskAboutReel in cedar/search_reels.cedar) answer "may this principal call this action at all" — a real, demonstrable policy object, actually evaluated at runtime via nylo_common.authz.is_authorized (cedarpy, no external service — see ADR-012), called at the top of search_agent.handler() and library_api.handler() before any data is touched. It does not do row-level filtering. The actual per-user isolation — stopping igsid A from ever seeing igsid B's reel — is application code scoping the DynamoDB/OpenSearch query to the caller's own media_ids (_fetch_user_media_ids / _fetch_user_reels / get_reel's ownership check). If you're writing documentation, a comment, or a demo script and you're about to describe Cedar as "filtering" or "restricting" results, stop — that's the overclaim this project explicitly corrected once already. Say "authorizes the action; the query scoping does the filtering." Two physical copies of the policy exist for packaging reasons (cedar/search_reels.cedar is canonical; layers/common/python/nylo_common/search_reels.cedar is what's actually loaded) — kept in sync by a test, not by hand; see cedar/README.md.

4. Frame sampling is capped at ~20 frames per reel. One frame every 2 seconds for reels under ~40s; for anything longer, 20 frames spread evenly across the whole duration instead of every 2 seconds. This is implemented in compute_frame_timestamps (src/ingestion/app.py) and is tested — don't reintroduce an uncapped version for "better accuracy." The cap exists to bound Bedrock's multimodal image count and cost on long reels.

5. Embeddings are always generated over transcript + caption + summary together — never the summary alone. A summary compresses away exact quantities, place names, and brand names that someone might search for later. If you're touching _embed in src/ingestion/app.py, all three inputs go in, every time.

6. Webhook handling must cover both messages and UNSUPPORTED events, and must not assume a clean attachment shape. Reel shares can arrive as an ig_post, ig_reel, or legacy share attachment on messages, or as a completely different UNSUPPORTED event (private-account media, voice notes, GIFs, and sometimes reels with no caption). _route_messaging_event in src/webhook_receiver/app.py checks both shapes for exactly this reason — don't simplify it down to "just handle ig_post."

7. Reel categories come from a fixed taxonomy, never freeform. The list lives in layers/common/python/nylo_common/categories.py (CATEGORY_TAXONOMY). Ingestion's Bedrock call must pick one of these, falling back to DEFAULT_CATEGORY ("Other") if the model's output doesn't match. A freeform tag per reel breaks the Library web app's "browse by category" view by producing dozens of near-duplicate categories.

8. Library web-app auth tokens are issued and verified through the shared nylo_common.token module (the nylo-common Lambda layer) — never reimplemented per-function. Divergence between the issuer (webhook_receiver) and the verifier (library_api) is a correctness bug, not a style choice, which is why this is the one piece of logic in the codebase that's shared via a layer instead of duplicated. Every library_api route must call _authenticate (or equivalent) before touching any data, and every reel-specific route must check ownership via UserReelLinks before returning reel content — see get_reel in src/library_api/app.py for the pattern.

9. The DM search agent's query embedding model must be the exact same Bedrock model as ingestion's document embedding model (BedrockEmbeddingModelId). Never introduce a second embedding-model parameter for search. Two different embedding models produce incompatible vector spaces — a mismatch here doesn't degrade kNN search quality, it makes the similarity scores meaningless. See _embed_query in src/search_agent/app.py.

10. IngestionFunction is packaged as a container image (PackageType: Image, Dockerfile.ingestion), not a Zip. Its dependencies (faster-whisper/ctranslate2 + strands-agents + imageio-ffmpeg's bundled binary) measure ~550MB, well past Lambda's 250MB Zip-package limit. Don't "simplify" it back to a normal CodeUri/requirements.txt Zip function without re-measuring the built size first. Image-packaged Lambdas can't use Runtime, Handler, or Layers — including inherited from SAM's Globals section, which is why Runtime is set per-function on the three Zip-packaged functions instead of globally, and why Dockerfile.ingestion COPYs the shared nylo_common module in directly instead of attaching CommonLayer.

Process rules

• Every new piece of non-trivial logic (a branch, a loop, a parser, anything touching money/ auth/security) ships with a test_*.py next to it. No test frameworks, no fixtures — plain assert-based functions, runnable directly (python src/whatever/test_app.py). This is already the pattern in every existing test_app.py in this repo; keep it going.
• Append to HISTORY.md after every meaningful change — what changed, how, and why, in about 100 words. HISTORY.md is append-only: never edit or delete a past entry, even if a later change reverses it. If you pivot away from something, add a new entry saying so; don't go back and rewrite the old one. This is the project's only record of why something is the way it is, for whoever reads it next.
• Stubs for work that needs live AWS/Meta credentials this repo can't provide (media fetch, ffmpeg, faster-whisper, Bedrock calls, OpenSearch queries, the actual Instagram reply) should raise NotImplementedError with a TODO comment saying exactly what's needed — not a fake return value that looks like it works.
• Before "fixing" anything that looks like a bug in the lock/race-condition handling, the frame cap, the embedding inputs, or the Cedar framing: read docs/DECISIONS.md. It's almost certainly deliberate and already explains why.