neuro-san: Instructions file for Codex

AGENTS.md

Rules for coding agents in neuro-san. Follow them and make sure the checks in §6 pass on the first run.

1. Contribution rules

• Agent networks are data-only HOCON files under neuro_san/registries/; manifest.hocon controls whether a network is served, publicly listed, and exposed via mcp — see manifest_hocon_reference.md.
• CodedTools live under neuro_san/coded_tools/, resolved via AGENT_TOOL_PATH. Mirror the registry's folder layout when a tool belongs to a specific network.
• No secrets in HOCON or code: read them from environment variables, or pass them per request via sly_data (see Client-Provided API Keys). Never log or print sly_data.
• Validate a HOCON file before opening a PR: python -m neuro_san.client.hocon_validator_cli path/to/agent.hocon --verbose (see hocon_validator_cli.md).
• Keep the diff focused: no unrequested refactors or reformatting of untouched files. Remove debug prints, commented-out code and stray TODOs before opening a PR.
• Update the matching reference doc in the same PR when you change documented behavior: agent_hocon_reference.md, external_agents.md, mcp_tools.md, provider_tools.md, manifest_hocon_reference.md, llm_info_hocon_reference.md, toolbox_info_hocon_reference.md, mcp_service.md, clients.md, tests.md, or test_case_hocon_reference.md. Verify every link in a document you touch.

2. Code style

• One module, one class. Each .py file defines exactly one class (a handful of pre-existing exceptions are not precedent). Split helper logic into a separate module rather than adding a second class to an existing file. This should also mean that there should be no module comments - they should be really be the class's docstring.
• No module over 1000 lines. That is pylint's too-many-lines limit, and CI checks it for source and tests alike. When a module would go over it, refactor instead of disabling the check: move whole concerns of the class, such as validation or formatting, into classes of their own, each in its own module. Tests split by topic (§3).
• No module-level functions, no nested functions, no lambdas. Every function is a method (or @staticmethod) on the module's class. If a method needs a helper, make it another method on the same class; bind arguments with functools.partial on a method or @staticmethod where a lambda would otherwise have been used.
• No comprehensions. Use explicit for loops instead of list/dict/set/generator comprehensions, even when a comprehension would be shorter.
• Always use type hints. Every function/method signature needs type hints for all parameters and the return type; annotate a variable assignment too when the type isn't obvious from the right-hand side.
• snake_case for functions, methods, variables, parameters and attributes; PascalCase for classes; UPPER_CASE for constants. Comment the reason if an external API forces camelCase.
• Read dictionary values with .get(), never dict[key]; plain subscript is fine for assignment (config["key"] = value).
• Catch the specific exceptions that can be handled at that level. Pylint flags a broad except Exception (W0718); where one is genuinely needed, add # pylint: disable=broad-exception-caught and state why in a comment.
• Never fail silently. Report a missing/unreadable file, malformed input, or an unknown choice with the full exception, and log enough to act on.
• Prefer logger over print, with lazy % formatting (logger.info("Loaded %s", name)) rather than f-strings.
• Use accessors, not internals: do not read another class's attributes directly and do not isinstance against a concrete class — check the interface, or add an interface method that answers the question.
• Docstrings on every class, function and method. A class docstring explains its purpose and responsibilities. A function/method docstring covers what it does, its parameters, its return value, and any exception it raises, in this exact format: