For AI Agents Modifying sql-redis¶
This section is the internal counterpart to the user-facing AGENTS.md. It exists for an agent that has been asked to change the library: add a new SQL feature, fix a parser bug, extend the schema registry.
Decision tree¶
Use this to find the right starting point fast.
| Task | Read first |
|---|---|
| Add a new SQL clause or operator | Repository map, then parser.py, then analyzer.py, then query_builder.py |
| Add a new field type (e.g., a future GEO variant) | Repository map, then analyzer.py and query_builder.py |
| Fix a translation bug | Repository map, then translator.py. Run integration tests under tests/test_sql_queries.py. |
| Change parameter substitution | Parameter substitution, then executor.py::_substitute_params |
| Change schema loading semantics | Schema-aware translation, then schema.py |
| Change async behavior | Async invariants, then executor.py::AsyncExecutor and schema.py::AsyncSchemaRegistry |
| Change the FT.SEARCH/FT.AGGREGATE branching | FT.SEARCH vs FT.AGGREGATE, then translator.py::translate_parsed |
| Change the result-row shape | Result shape, then executor.py (Executor.execute parsing branches) |
| Run tests | Build and test |
| Diagnose "this looks broken" | Failure modes before assuming a bug |
Project invariants the agent should preserve¶
- No mocks for Redis in integration tests. Real
testcontainers[redis]only. See Testing philosophy. - 100% line coverage is enforced in CI. No
# pragma: no cover. If a branch can't be tested, it shouldn't exist. - Public API is what
sql_redis/__init__.pyexports. Anything else is internal and can change without notice. The mkdocstrings-driven reference atdocs/api/is the contract. - Docstrings are the single source of truth for the API reference. mkdocstrings reads them directly. If you change a method signature, update the docstring in the same change.
- No emdashes or
--in prose. Stylistic rule from the project'sCLAUDE.md.