spec-objects-architecture

Filament Module: tier-2 architecture ObjectTypes (api_endpoint, data_schema, queue, action, ui_component, rate_limit, interface, external_contract, extension_point, binary_format)

This is an Agent-IX Filament module loaded by quire-cli and quoin. It provides tier-2 embedded object_types — a manifest.yaml plus per-kind authoring skeletons/ used to author and validate Markdown spec artifacts.

Installing quire-cli

@agent-ix packages are published to public npm. Install the CLI globally:

npm install -g @agent-ix/quire-cli

See https://github.com/agent-ix/quire-cli#install for details.

Install this module via npm

This module is also published as a config-only npm package: @agent-ix/spec-objects-architecture. The package root is the Filament module (manifest.yaml + schemas/skeletons), so it works directly as a --module target or via quoin's package: source.

npm install @agent-ix/spec-objects-architecture

# quoin — resolve the module from npm by name
quoin plugin install package:@agent-ix/spec-objects-architecture

# or point any tool at the installed package root
quire validate spec/**/*.md --module node_modules/@agent-ix/spec-objects-architecture

Object types provided

Object	type:	Description
API endpoint	api_endpoint	An HTTP endpoint surface: a required Endpoint section describing what it does plus its method/path routes, and an optional 2. API Contract section for request/response/auth detail.
Data schema	data_schema	A JSON-shaped record defined by a required Schema section holding a JSON Schema (draft 2020-12) code block.
Queue	queue	A message queue defined by a required Message Format section holding an example JSON message payload (or its schema).
Action	action	A discrete action/task defined by a required Inputs section listing every input it consumes, with type and source.
UI component	ui_component	A frontend component defined by a required Props section enumerating every prop with name, type, and behavior.
Rate limit	rate_limit	A throttling policy defined by a required Thresholds section listing the concrete limits, windows, and the response when a limit is exceeded.
Interface	interface	A language-neutral operations contract within the system, defined by a required Contract section holding a YAML code block (name, types, operations, invariants).
External contract	external_contract	A contract with a system outside this one, with a required Contract section plus optional Endpoints and Behavior sections for the consumed/exposed surface and interaction semantics.
Extension point	extension_point	First-class pluggability: a required Contract section naming the interface it exposes, plus optional Registration and Stability sections for discovery and compatibility guarantees.
Binary format	binary_format	A persisted binary layout defined by a required Layout section holding a YAML code block of record types with per-field name/offset/size/type/endianness.

How this module is used

With quoin (recommended)

Install this module as a plugin, then author and review spec artifacts:

quoin plugin install path:../spec-objects-architecture
quoin catalog list
quoin write . --types api_endpoint,data_schema
quoin review

See quoin for details.

With quire-cli directly

Point quire at this module's package directory to fetch a skeleton, validate documents, or extract a document's structured body:

quire schema api_endpoint --module ./spec_objects_architecture
quire validate spec/**/*.md --module ./spec_objects_architecture
quire extract spec/upload-artifact.md --module ./spec_objects_architecture

See quire-cli#usage-instructions for details.

Development

• Library name: spec_objects_architecture (flat layout, package at repo root)
• Language / tooling: Python 3.13+, Poetry, GitHub Actions CI
• Versioning: dynamic, Git-tag-based
• Publishing: Google Artifact Registry (PyPI-compatible) via twine upload -r internal-pypi in CI on tag v*.*.*

Common Makefile targets:

Target	Description
install	Install dependencies in Poetry venv
test	Run tests (pytest)
lint	Run linting (Ruff + Black check)
format	Auto-format code (Ruff + Black)
build	Build wheel and sdist under dist/
update-lock	Update poetry.lock
update-packages	Update all dependencies
add-package p=<name>	Add a runtime dependency
add-dev-package p=<name>	Add a dev dependency
use-local p=<name>	Switch a dep to local pypi.ix
use-upstream p=<name>	Switch a dep back to upstream
local-publish	Build and publish to local PyPI (pypi.ix)