Project

AtlasboxPy

One call path for REST routes, workers, and agents

Public

GitHub

Overview

AtlasboxPy is a shared Python controller package (atlasboxpy_controller, formerly validator_gateway) built around one idea: business-rule validation, error formatting, and response shaping belong to the domain, not to whichever transport happens to be calling it. A BaseController base class wraps every public method automatically at class-definition time, so a REST route, a background worker, and an in-process agent all get identical guarantees — the same call path, the same typed DomainError hierarchy, and the same structured retryable signal — without adapter code written on any caller's behalf.

Problem

Frameworks like FastAPI and Pydantic make request validation feel solved — but only for the one HTTP caller most APIs are originally built around. Business rules, error handling, and response formatting quietly become the HTTP layer's job, written under the assumption that a single waiting browser is the only caller that will ever exist. That assumption breaks the moment a background worker, an autonomous agent, or another internal service needs the exact same logic: duplicating it drifts silently, and routing a same-process call over the existing REST API just to reuse validation turns a function call into a distributed-systems problem.

Architecture

AtlasboxPy's architecture spans:

  • BaseController — wraps every public method automatically, no separate gateway object to construct
  • A typed DomainError hierarchy carrying HTTP/gRPC status mappings and a real retryable flag
  • is_retryable(code) — a structured, checkable signal for callers (including unattended agents) instead of a message string to guess at
  • A queryable tool_dictionary registering internally-owned and agent-callable methods
  • A decision rule reserving MCP for genuine ownership boundaries — a different team, company, or runtime — rather than every agent tool call by default
  • A deprecation-window requirement for agent-callable controller methods, enforced via the same registry

Engineering Decisions

AtlasboxPy's design choices are documented as real, embedded Architecture Decision Records rather than after-the-fact justifications — each states its own problem, solution, scored trade-offs, and alternatives considered:

Screenshots

VS Code file tree of AtlasboxPy's full packages/ directory: atlasboxpy_api, atlasboxpy_controller, atlasboxpy_db, atlasboxpy_repository, atlasboxpy_service, and atlasboxpy_telemetry, each with its own docs, src, tests, LICENSE, NOTICE, pyproject.toml, and README.md.
The full packages/ directory from the private project — all six packages, each shipped as its own self-contained package with docs, tests, and a README. See Packages above for what each one does.

Publications

The Validation Layer That's Trapped Inside Your HTTP Framework

MCP is for Strangers

Inside the AtlasboxPy API Stack

Repository

github.com/NDutraConsulting/AtlasboxPy

The public repository above is a stripped-down, polished code example — it demonstrates the pattern, but it does not contain the full project. The complete package set is listed below.

Packages

atlasboxpy_controller and atlasboxpy_repository are the two packages included in the public GitHub sample above; the remaining four ship only with the full project.