Auto-generation Engine

Auto-generation Engine

One decorated Python function. One HTTP endpoint. One CLI command. Zero boilerplate.

Core Platform — Full Pipeline

@service_method

decorator

→

Registry

global dict

→

http_generator.py

startup

→

FastAPI Router

built dynamically

↓

/v1/{service}/{method}

HTTP endpoints

↓

/v1/meta

schema endpoint

↓

Constellation Lite

schema cache + Typer app

↓

CLI commands

constellation github get-repository

What & Why

Octopus's auto-generation engine is the single source of truth for every integration method.

When you write a new integration, you write one decorated Python function. The engine does the rest:

Output	How it's produced
POST /github/get-repository	http_generator.py creates a FastAPI route at startup
constellation github get-repository --owner X --repo Y	Constellation Lite builds a Typer command from the /meta schema
Entry in GET /v1/meta	build_meta_router introspects the registry at startup

No OpenAPI YAML. No CLI glue code. No sync between server and client. Every new method is immediately available on all three surfaces.

The @service_method Decorator

Decorator internals

Method definition

function + type hints + docstring

→

@service_method wraps

stores ServiceMethodMeta on wrapper._service_method_meta

→

ServiceRegistry

service_registry.register(name, cls)

ServiceMethodMeta captures

• description (docstring)
• method_name
• tags (optional)

http_generator.py reads

• inspect.signature() for param names + types
• _infer_http_method() from name prefix
• _method_name_to_path() snake→kebab

The description argument to @service_method becomes both the FastAPI route summary and the Typer command help string. The HTTP verb is inferred automatically from the method name prefix (list_ / get_ / search_ → GET, create_ / send_ → POST, update_ → PATCH, delete_ / remove_ → DELETE).

CLI Schema Discovery Flow

Constellation Lite — schema bootstrap

CONSTELLATION_SERVER_URL

env var (required)

→

GET /v1/meta

HTTP request

→

Cache check

~/.constellation/schema.json
1-hour TTL

→

Typer app built

build_cli_app()

→

Subcommands ready

one group per service
one cmd per method

Cache HIT — reads schema.json directly, no network call

Cache MISS / stale — fetches /v1/meta, writes schema.json with fetched_at timestamp

Network error + stale cache — warns and uses stale schema; hard-fails only if no cache exists at all

The schema is fetched once per hour per machine. CONSTELLATION_API_KEY is forwarded as X-API-KEY during the fetch if set.

Reference

Minimal decorated method

# apps/constellation/app/services/github/service.py

from app.core.generator.decorator import service_method
from app.core.generator.context import RequestContext

class GitHubService:
    def __init__(self, ctx: RequestContext):
        self.ctx = ctx

    @service_method(description="Get repository details")
    async def get_repository(self, owner: str, repo: str) -> dict:
        # ... implementation
        return {"owner": owner, "repo": repo, "default_branch": "main"}

This single function automatically produces all three of the following.

Resulting HTTP endpoint

GET /github/get-repository?owner=octocat&repo=hello-world

• HTTP verb inferred from get_ prefix → GET
• Path: /{service_name}/{method-name-in-kebab-case}
• Parameters become FastAPI Query params for GET, Body params for POST/PATCH/DELETE
• Auth extracted from Authorization header (JWT) or Access-Token header

Resulting CLI command

constellation github get-repository --owner octocat --repo hello-world

• Subcommand group: github (from service name)
• Subcommand: get-repository (snake_case → kebab-case)
• Options: one --{param-name} flag per parameter
• --output-mode flag available on every command (agent | json | csv | xml | plaintext)

Appearance in /meta

{
  "services": [
    {
      "name": "github",
      "methods": [
        {
          "name": "get_repository",
          "description": "Get repository details",
          "http_method": "GET",
          "path": "/github/get-repository",
          "params": [
            {"name": "owner", "type": "str", "default": null, "required": true},
            {"name": "repo",  "type": "str", "default": null, "required": true}
          ]
        }
      ]
    }
  ]
}

HTTP verb inference rules

Method name prefix	HTTP verb
list_, get_, search_, fetch_	GET
create_, send_, add_	POST
update_	PATCH
delete_, remove_	DELETE
(anything else)	POST

Type mapping (Python → meta schema → Typer)

Python annotation	/v1/meta type	CLI option type
str	str	Optional[str]
int	int	Optional[int]
float	float	Optional[float]
bool	bool	Optional[bool]
list, dict, complex generics	json	Optional[str] (JSON-encoded)
Optional[X] / X | None	unwrapped to inner type	same as inner