Mas Function Design

MAS Function Design

Objective

Design backend functions that are predictable, easy to trace, and easy to evolve.

Core Principles

1. Keep one primary responsibility per function.
2. Make data flow explicit through inputs and return values.
3. Minimize hidden side effects and shared mutable state.
4. Keep error semantics stable and actionable.
5. Match function placement with module boundary ownership.

Responsibility

1. Keep a function focused on one decision unit or one orchestration step.
2. Split when a function mixes domain decision and integration IO.
3. Split when one function serves unrelated call paths.
4. Keep thin wrappers thin; move real logic only when it creates real reuse.
5. Do not extract a helper for logic that is easier to understand inline at the call site.
6. For frequently edited task-configuration code, keep the mutation block in the owning orchestration function with a short purpose comment and blank lines around it.
7. Do not split one linear task flow into builder/loader helpers unless the split removes real duplication or clarifies a true boundary.
8. In AUTO-MAS task flows, keep config import/export, log monitoring, and end-state judgment as explicit orchestration steps; do not hide product-critical run criteria behind vague wrappers.

Signatures And Returns

1. Use explicit named parameters for business-critical options.
2. Avoid ambiguous boolean positional parameters.
3. Group related data in typed models/dataclasses when argument count grows.
4. Keep optional parameters truly optional with clear default meaning.
5. Return one stable shape per function role.
6. Return domain values, not transport-layer response objects.
7. Prefer signatures that remain compatible with basic static type checking.
8. If omission is a valid state, omit the argument or field instead of passing a typed placeholder that conflicts with the signature.
9. Use positional arguments only for simple, obvious calls with at most two clear parameters.
10. Use keyword arguments for boolean arguments and for calls with more than two parameters.

Error Handling

1. Raise domain-meaningful exceptions at domain layers.
2. Convert exceptions to API-safe output only at API boundary.
3. Do not swallow exceptions without logging context and fallback reason.
4. Keep retry logic near integration boundaries, not in pure helpers.
5. Include enough context in errors for diagnosis (script_id, user_id, step).

Side Effects And Async

1. Keep file IO, network, process, and global state operations explicit.
2. Isolate side effects behind service/helper functions.
3. In pure transformation functions, avoid logging and external calls.
4. Do not mutate input objects unless the contract explicitly states mutation.
5. Use async only when awaiting IO or async coordination primitives.
6. Keep cancellation-safe cleanup in finally blocks for long-running flows.
7. Avoid mixing sync blocking calls directly in async hot paths.
8. Do not ship a function body containing module lazy imports to a thread pool (asyncio.to_thread/run_in_executor): resolve imports on the event loop or at startup, then pass the imported callables to the thread. Concurrent cold imports of one package from multiple worker threads can deadlock on CPython's per-module import locks or observe half-initialized modules.
9. Keep task spawning in orchestrator-level functions, not leaf utilities.
10. Trust existing base-layer guarantees instead of repeating their correction logic in every function.
11. Prefer one clear wait/check block over several tiny sleeps, logs, or staged wrappers that express the same step.
12. When success/failure depends on log text, log timestamps, and process exit together, keep that decision rule centralized and readable instead of scattering partial checks across helpers.
13. TaskExecuteBase.main_task, final_task, and on_crash are the required execution contract for task classes; keep their responsibilities distinct.
14. main_task and final_task may raise normally, but on_crash must protect itself from uncaught exceptions.
15. Await child task spawning through await self.spawn(...); do not fire child tasks without awaiting unless the owning orchestration has a documented reason.
16. Use .cancel() plus await .accomplish.wait() when parent code must wait for nested task shutdown and cleanup to finish.