vs-server 0.1.2__tar.gz → 0.1.4__tar.gz

{vs_server-0.1.2/vs_server.egg-info → vs_server-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vs-server
-Version: 0.1.2
+Version: 0.1.4
 Summary: HTTP server abstraction for Viveka Sutra — FastAPI wrapper with lifecycle, routing, and middleware
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -348,6 +348,52 @@ All server config lives under the `[server]` section of `config.ini`.
 | `server.ssl_keyfile_password` | — | Password for encrypted private key |
 | `api.cors_origins` | `*` | Comma-separated allowed CORS origins |
 
+These keys apply to all `VsServer` implementations. Framework-specific config lives in its own section.
+
+### FastAPI-specific config (`[fastapi]`)
+
+| Key | Default | Description |
+|---|---|---|
+| `fastapi.workers` | `1` | Number of worker processes. Requires `fastapi.app_import` to be set. |
+| `fastapi.reload` | `false` | Enable hot reload (dev only). Requires `fastapi.app_import` to be set. |
+| `fastapi.log_level` | `info` | Uvicorn log level (`debug`, `info`, `warning`, `error`) |
+| `fastapi.app_import` | — | Import string for multi-worker or reload mode, e.g. `my_service.app:server`. Required when `workers > 1` or `reload = true`. |
+
+**`config.ini` example for multi-worker production:**
+
+```ini
+[server]
+name = my-service
+version = 1.0.0
+host = 0.0.0.0
+port = 8000
+docs_enabled = false
+
+[fastapi]
+workers = 4
+log_level = warning
+app_import = my_service.app:server
+
+[api]
+cors_origins = https://app.example.com
+```
+
+**What is `app_import`?**
+
+When running multiple workers, uvicorn forks child processes that each need to reconstruct the app independently. They can't share the in-memory object from the parent process — they need an import path to build their own copy.
+
+`app_import` is `module.path:variable_name` where `variable_name` is whatever you assigned `VsServerFactory.get()` to:
+
+```python
+# my_service/app.py
+server = VsServerFactory.get("fastapi", config)  # → app_import = my_service.app:server
+server.run()
+```
+
+If `app_import` is not set, vs-server will attempt to auto-detect it and log it at startup. Copy the logged value into your config to make it explicit.
+
+**Custom server implementations** follow the same pattern — add a `[my_framework]` section in `config.ini` for any framework-specific keys and read them in your `VsServer` subclass.
+
 **`config.ini` example:**
 
 ```ini
@@ -469,6 +515,57 @@ async def get_report():
 
 ---
 
+## Request and Response Models
+
+All request bodies and response models must be Pydantic models — not SQLAlchemy entities or plain dicts. This is a hard requirement of FastAPI and applies to all server implementations built on vs-server.
+
+```python
+from pydantic import BaseModel
+
+class UserRequest(BaseModel):
+    name: str
+    email: str
+
+class UserResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+
+    model_config = {"from_attributes": True}
+```
+
+The mapping between your SQLAlchemy entity and your Pydantic schema is your responsibility:
+
+```
+Request (Pydantic) → Service → Entity (SQLAlchemy) → DB
+DB → Entity (SQLAlchemy) → Service → Response (Pydantic)
+```
+
+Never pass a SQLAlchemy entity as `response_model` — FastAPI will reject it at startup. Never return a SQLAlchemy entity directly from a route — serialize it first.
+
+Keeping schemas separate from entities is intentional: the DB schema and API schema can evolve independently, and sensitive fields (e.g. `password`) are excluded from responses by default.
+
+### @model — Reduce Schema Boilerplate (requires vs-db)
+
+If you are using `vs-db`, the `@model` decorator derives Pydantic fields directly from a SQLAlchemy entity so you don't repeat type definitions. Nullable columns become `Optional[T] = None` automatically. Fields already defined on the class are never overridden.
+
+```python
+from pydantic import BaseModel, Field
+from vs_db.decorator.vs_model_decorator import model
+
+@model(AppUser, exclude=["password"])
+class UserResponse(BaseModel):
+    pass  # all AppUser fields injected except password
+
+@model(AppUser, include=["email", "first_name", "last_name"])
+class CreateUserRequest(BaseModel):
+    first_name: str = Field(min_length=1)  # user-defined — decorator skips it
+```
+
+See the `vs-db` README for full documentation on `@model`.
+
+---
+
 ## HTTP Controllers
 
 Annotate a class with `@controller` and methods with HTTP verb decorators.
@@ -520,11 +617,11 @@ All FastAPI route parameters (`response_model`, `status_code`, `tags`, `summary`
 
 | Decorator | HTTP Method |
 |---|---|
-| `@get(path, guards=[], **kwargs)` | GET |
-| `@post(path, guards=[], **kwargs)` | POST |
-| `@put(path, guards=[], **kwargs)` | PUT |
-| `@delete(path, guards=[], **kwargs)` | DELETE |
-| `@patch(path, guards=[], **kwargs)` | PATCH |
+| `@get(path, summary, description, guards=[], **kwargs)` | GET |
+| `@post(path, summary, description, guards=[], **kwargs)` | POST |
+| `@put(path, summary, description, guards=[], **kwargs)` | PUT |
+| `@delete(path, summary, description, guards=[], **kwargs)` | DELETE |
+| `@patch(path, summary, description, guards=[], **kwargs)` | PATCH |
 
 Guards on a method are merged with controller-level guards — both run.
 
@@ -986,9 +1083,10 @@ Override template methods to customise behaviour:
 |---|---|---|
 | `get_host()` | Reads `server.host` | Hard-code or compute the bind address |
 | `get_port()` | Reads `server.port` | Hard-code or compute the bind port |
-| `get_reload()` | Reads `server.reload` | Force hot-reload on/off |
-| `get_workers()` | Reads `server.workers` | Set worker count programmatically |
-| `get_log_level()` | Reads `server.log_level` | Set log level programmatically |
+| `get_reload()` | FastAPI only — reads `fastapi.reload` | Force hot-reload on/off |
+| `get_workers()` | FastAPI only — reads `fastapi.workers` | Set worker count programmatically |
+| `get_log_level()` | FastAPI only — reads `fastapi.log_level` | Set log level programmatically |
+| `get_app_import()` | FastAPI only — reads `fastapi.app_import` | Return import string for multi-worker mode |
 | `get_ssl_certfile()` | Reads `server.ssl_certfile` | Load cert from a secret store |
 | `get_ssl_keyfile()` | Reads `server.ssl_keyfile` | Load key from a secret store |
 | `get_ssl_keyfile_password()` | Reads `server.ssl_keyfile_password` | Load password from a secret store |
@@ -1164,8 +1262,10 @@ Route decorators. Applied to methods inside a `@controller` class.
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `path` | `str` | No | `""` | Route path appended to the controller prefix |
+| `summary` | `str` | No | `None` | Short one-line description shown in Swagger |
+| `description` | `str` | No | `None` | Longer description shown in Swagger |
 | `guards` | `List[Callable]` | No | `[]` | Merged with controller guards |
-| `**kwargs` | — | No | — | Passed to the underlying FastAPI route decorator (e.g. `response_model`, `status_code`, `summary`) |
+| `**kwargs` | — | No | — | Passed to the underlying FastAPI route decorator (e.g. `response_model`, `status_code`) |
 
 ---
 

{vs_server-0.1.2 → vs_server-0.1.4}/README.md

@@ -129,6 +129,52 @@ All server config lives under the `[server]` section of `config.ini`.
 | `server.ssl_keyfile_password` | — | Password for encrypted private key |
 | `api.cors_origins` | `*` | Comma-separated allowed CORS origins |
 
+These keys apply to all `VsServer` implementations. Framework-specific config lives in its own section.
+
+### FastAPI-specific config (`[fastapi]`)
+
+| Key | Default | Description |
+|---|---|---|
+| `fastapi.workers` | `1` | Number of worker processes. Requires `fastapi.app_import` to be set. |
+| `fastapi.reload` | `false` | Enable hot reload (dev only). Requires `fastapi.app_import` to be set. |
+| `fastapi.log_level` | `info` | Uvicorn log level (`debug`, `info`, `warning`, `error`) |
+| `fastapi.app_import` | — | Import string for multi-worker or reload mode, e.g. `my_service.app:server`. Required when `workers > 1` or `reload = true`. |
+
+**`config.ini` example for multi-worker production:**
+
+```ini
+[server]
+name = my-service
+version = 1.0.0
+host = 0.0.0.0
+port = 8000
+docs_enabled = false
+
+[fastapi]
+workers = 4
+log_level = warning
+app_import = my_service.app:server
+
+[api]
+cors_origins = https://app.example.com
+```
+
+**What is `app_import`?**
+
+When running multiple workers, uvicorn forks child processes that each need to reconstruct the app independently. They can't share the in-memory object from the parent process — they need an import path to build their own copy.
+
+`app_import` is `module.path:variable_name` where `variable_name` is whatever you assigned `VsServerFactory.get()` to:
+
+```python
+# my_service/app.py
+server = VsServerFactory.get("fastapi", config)  # → app_import = my_service.app:server
+server.run()
+```
+
+If `app_import` is not set, vs-server will attempt to auto-detect it and log it at startup. Copy the logged value into your config to make it explicit.
+
+**Custom server implementations** follow the same pattern — add a `[my_framework]` section in `config.ini` for any framework-specific keys and read them in your `VsServer` subclass.
+
 **`config.ini` example:**
 
 ```ini
@@ -250,6 +296,57 @@ async def get_report():
 
 ---
 
+## Request and Response Models
+
+All request bodies and response models must be Pydantic models — not SQLAlchemy entities or plain dicts. This is a hard requirement of FastAPI and applies to all server implementations built on vs-server.
+
+```python
+from pydantic import BaseModel
+
+class UserRequest(BaseModel):
+    name: str
+    email: str
+
+class UserResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+
+    model_config = {"from_attributes": True}
+```
+
+The mapping between your SQLAlchemy entity and your Pydantic schema is your responsibility:
+
+```
+Request (Pydantic) → Service → Entity (SQLAlchemy) → DB
+DB → Entity (SQLAlchemy) → Service → Response (Pydantic)
+```
+
+Never pass a SQLAlchemy entity as `response_model` — FastAPI will reject it at startup. Never return a SQLAlchemy entity directly from a route — serialize it first.
+
+Keeping schemas separate from entities is intentional: the DB schema and API schema can evolve independently, and sensitive fields (e.g. `password`) are excluded from responses by default.
+
+### @model — Reduce Schema Boilerplate (requires vs-db)
+
+If you are using `vs-db`, the `@model` decorator derives Pydantic fields directly from a SQLAlchemy entity so you don't repeat type definitions. Nullable columns become `Optional[T] = None` automatically. Fields already defined on the class are never overridden.
+
+```python
+from pydantic import BaseModel, Field
+from vs_db.decorator.vs_model_decorator import model
+
+@model(AppUser, exclude=["password"])
+class UserResponse(BaseModel):
+    pass  # all AppUser fields injected except password
+
+@model(AppUser, include=["email", "first_name", "last_name"])
+class CreateUserRequest(BaseModel):
+    first_name: str = Field(min_length=1)  # user-defined — decorator skips it
+```
+
+See the `vs-db` README for full documentation on `@model`.
+
+---
+
 ## HTTP Controllers
 
 Annotate a class with `@controller` and methods with HTTP verb decorators.
@@ -301,11 +398,11 @@ All FastAPI route parameters (`response_model`, `status_code`, `tags`, `summary`
 
 | Decorator | HTTP Method |
 |---|---|
-| `@get(path, guards=[], **kwargs)` | GET |
-| `@post(path, guards=[], **kwargs)` | POST |
-| `@put(path, guards=[], **kwargs)` | PUT |
-| `@delete(path, guards=[], **kwargs)` | DELETE |
-| `@patch(path, guards=[], **kwargs)` | PATCH |
+| `@get(path, summary, description, guards=[], **kwargs)` | GET |
+| `@post(path, summary, description, guards=[], **kwargs)` | POST |
+| `@put(path, summary, description, guards=[], **kwargs)` | PUT |
+| `@delete(path, summary, description, guards=[], **kwargs)` | DELETE |
+| `@patch(path, summary, description, guards=[], **kwargs)` | PATCH |
 
 Guards on a method are merged with controller-level guards — both run.
 
@@ -767,9 +864,10 @@ Override template methods to customise behaviour:
 |---|---|---|
 | `get_host()` | Reads `server.host` | Hard-code or compute the bind address |
 | `get_port()` | Reads `server.port` | Hard-code or compute the bind port |
-| `get_reload()` | Reads `server.reload` | Force hot-reload on/off |
-| `get_workers()` | Reads `server.workers` | Set worker count programmatically |
-| `get_log_level()` | Reads `server.log_level` | Set log level programmatically |
+| `get_reload()` | FastAPI only — reads `fastapi.reload` | Force hot-reload on/off |
+| `get_workers()` | FastAPI only — reads `fastapi.workers` | Set worker count programmatically |
+| `get_log_level()` | FastAPI only — reads `fastapi.log_level` | Set log level programmatically |
+| `get_app_import()` | FastAPI only — reads `fastapi.app_import` | Return import string for multi-worker mode |
 | `get_ssl_certfile()` | Reads `server.ssl_certfile` | Load cert from a secret store |
 | `get_ssl_keyfile()` | Reads `server.ssl_keyfile` | Load key from a secret store |
 | `get_ssl_keyfile_password()` | Reads `server.ssl_keyfile_password` | Load password from a secret store |
@@ -945,8 +1043,10 @@ Route decorators. Applied to methods inside a `@controller` class.
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `path` | `str` | No | `""` | Route path appended to the controller prefix |
+| `summary` | `str` | No | `None` | Short one-line description shown in Swagger |
+| `description` | `str` | No | `None` | Longer description shown in Swagger |
 | `guards` | `List[Callable]` | No | `[]` | Merged with controller guards |
-| `**kwargs` | — | No | — | Passed to the underlying FastAPI route decorator (e.g. `response_model`, `status_code`, `summary`) |
+| `**kwargs` | — | No | — | Passed to the underlying FastAPI route decorator (e.g. `response_model`, `status_code`) |
 
 ---
 

{vs_server-0.1.2 → vs_server-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vs-server"
-version = "0.1.2"
+version = "0.1.4"
 description = "HTTP server abstraction for Viveka Sutra — FastAPI wrapper with lifecycle, routing, and middleware"
 readme = "README.md"
 requires-python = ">=3.11"

vs_server-0.1.4/vs_server/decorator/vs_controller_decorator.py

@@ -0,0 +1,48 @@
+from typing import Callable, List, Type
+
+
+def controller(path: str, description: str = "", guards: List[Callable] = None):
+    def decorator(cls: Type) -> Type:
+        cls._vs_controller = {
+            "path": path,
+            "description": description,
+            "guards": guards or [],
+        }
+        return cls
+    return decorator
+
+
+def _route(method: str, path: str = "", guards: List[Callable] = None, summary: str = None, description: str = None, **kwargs):
+    def decorator(fn: Callable) -> Callable:
+        fn._vs_route = {
+            "method": method,
+            "path": path,
+            "guards": guards or [],
+            "kwargs": {
+                **({"summary": summary} if summary else {}),
+                **({"description": description} if description else {}),
+                **kwargs,
+            },
+        }
+        return fn
+    return decorator
+
+
+def get(path: str = "", guards: List[Callable] = None, summary: str = None, description: str = None, **kwargs):
+    return _route("GET", path, guards=guards, summary=summary, description=description, **kwargs)
+
+
+def post(path: str = "", guards: List[Callable] = None, summary: str = None, description: str = None, **kwargs):
+    return _route("POST", path, guards=guards, summary=summary, description=description, **kwargs)
+
+
+def put(path: str = "", guards: List[Callable] = None, summary: str = None, description: str = None, **kwargs):
+    return _route("PUT", path, guards=guards, summary=summary, description=description, **kwargs)
+
+
+def delete(path: str = "", guards: List[Callable] = None, summary: str = None, description: str = None, **kwargs):
+    return _route("DELETE", path, guards=guards, summary=summary, description=description, **kwargs)
+
+
+def patch(path: str = "", guards: List[Callable] = None, summary: str = None, description: str = None, **kwargs):
+    return _route("PATCH", path, guards=guards, summary=summary, description=description, **kwargs)

{vs_server-0.1.2 → vs_server-0.1.4}/vs_server/server/vs_fast_api_server.py

@@ -167,6 +167,18 @@ class VsFastApiServer(VsServer):
     def get_app(self):
         return self._app
 
+    def get_reload(self) -> bool:
+        return self._config.get("fastapi.reload", False, bool)
+
+    def get_workers(self) -> int:
+        return self._config.get("fastapi.workers", 1, int)
+
+    def get_log_level(self) -> str:
+        return self._config.get("fastapi.log_level", "info").lower()
+
+    def get_app_import(self) -> Optional[str]:
+        return self._config.get("fastapi.app_import")
+
     def run(self) -> None:
         import uvicorn
         host = self.get_host()
@@ -174,14 +186,19 @@ class VsFastApiServer(VsServer):
         reload = self.get_reload()
         workers = self.get_workers()
         log_level = self.get_log_level()
+        app_import = self.get_app_import()
         ssl_certfile = self.get_ssl_certfile()
         ssl_keyfile = self.get_ssl_keyfile()
         ssl_keyfile_password = self.get_ssl_keyfile_password()
 
-        self._print_banner(host, port, reload, tls=bool(ssl_certfile and ssl_keyfile))
+        self._print_banner(host, port, reload, workers, tls=bool(ssl_certfile and ssl_keyfile))
+
+        use_import = workers > 1 or reload
+        if use_import and not app_import:
+            app_import = self._detect_app_import()
 
         uvicorn_config = {
-            "app": self._app,
+            "app": app_import if use_import and app_import else self._app,
             "host": host,
             "port": port,
             "log_level": log_level,
@@ -189,7 +206,13 @@ class VsFastApiServer(VsServer):
         if reload:
             uvicorn_config["reload"] = True
         elif workers > 1:
-            uvicorn_config["workers"] = workers
+            if app_import:
+                uvicorn_config["workers"] = workers
+            else:
+                self._logger.warning(
+                    "fastapi.workers > 1 requires fastapi.app_import to be set in config.ini. "
+                    "Falling back to 1 worker."
+                )
 
         if ssl_certfile and ssl_keyfile:
             uvicorn_config["ssl_certfile"] = ssl_certfile
@@ -199,6 +222,21 @@ class VsFastApiServer(VsServer):
 
         uvicorn.run(**uvicorn_config)
 
+    def _detect_app_import(self) -> Optional[str]:
+        try:
+            import __main__
+            module = __main__.__spec__.name if hasattr(__main__, "__spec__") and __main__.__spec__ else None
+            if not module:
+                return None
+            for var_name, val in vars(__main__).items():
+                if val is self._app:
+                    detected = f"{module}:{var_name}"
+                    self._logger.info(f"Detected app_import = {detected}  (set fastapi.app_import in config.ini to make this explicit)")
+                    return detected
+        except Exception:
+            pass
+        return None
+
     # ------------------------------------------------------------------
     # Internal
     # ------------------------------------------------------------------
@@ -317,16 +355,17 @@ class VsFastApiServer(VsServer):
             )(fn)
         app.include_router(router)
 
-    def _print_banner(self, host: str, port: int, reload: bool, tls: bool = False) -> None:
+    def _print_banner(self, host: str, port: int, reload: bool, workers: int = 1, tls: bool = False) -> None:
         mode = "Development (reload)" if reload else "Production"
         scheme = "https" if tls else "http"
         self._logger.info("=" * 50)
         self._logger.info(f"  {self.name}  v{self.version}")
         self._logger.info("=" * 50)
-        self._logger.info(f"  Host   : {host}")
-        self._logger.info(f"  Port   : {port}")
-        self._logger.info(f"  Mode   : {mode}")
-        self._logger.info(f"  TLS    : {'enabled' if tls else 'disabled'}")
+        self._logger.info(f"  Host    : {host}")
+        self._logger.info(f"  Port    : {port}")
+        self._logger.info(f"  Mode    : {mode}")
+        self._logger.info(f"  Workers : {workers}")
+        self._logger.info(f"  TLS     : {'enabled' if tls else 'disabled'}")
         if self.is_docs_enabled() and self.get_docs_url():
             self._logger.info(f"  Docs   : {scheme}://{host}:{port}{self.get_docs_url()}")
             self._logger.info(f"  WS/SSE : {scheme}://{host}:{port}/vs-docs")

{vs_server-0.1.2 → vs_server-0.1.4}/vs_server/server/vs_server.py

@@ -48,15 +48,6 @@ class VsServer(ABC):
     def get_port(self) -> int:
         return self._config.get("server.port", 8000, int)
 
-    def get_reload(self) -> bool:
-        return self._config.get("server.reload", False, bool)
-
-    def get_workers(self) -> int:
-        return self._config.get("server.workers", 1, int)
-
-    def get_log_level(self) -> str:
-        return self._config.get("server.log_level", "info").lower()
-
     def get_ssl_certfile(self) -> Optional[str]:
         return self._config.get("server.ssl_certfile")
 

{vs_server-0.1.2 → vs_server-0.1.4/vs_server.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vs-server
-Version: 0.1.2
+Version: 0.1.4
 Summary: HTTP server abstraction for Viveka Sutra — FastAPI wrapper with lifecycle, routing, and middleware
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -348,6 +348,52 @@ All server config lives under the `[server]` section of `config.ini`.
 | `server.ssl_keyfile_password` | — | Password for encrypted private key |
 | `api.cors_origins` | `*` | Comma-separated allowed CORS origins |
 
+These keys apply to all `VsServer` implementations. Framework-specific config lives in its own section.
+
+### FastAPI-specific config (`[fastapi]`)
+
+| Key | Default | Description |
+|---|---|---|
+| `fastapi.workers` | `1` | Number of worker processes. Requires `fastapi.app_import` to be set. |
+| `fastapi.reload` | `false` | Enable hot reload (dev only). Requires `fastapi.app_import` to be set. |
+| `fastapi.log_level` | `info` | Uvicorn log level (`debug`, `info`, `warning`, `error`) |
+| `fastapi.app_import` | — | Import string for multi-worker or reload mode, e.g. `my_service.app:server`. Required when `workers > 1` or `reload = true`. |
+
+**`config.ini` example for multi-worker production:**
+
+```ini
+[server]
+name = my-service
+version = 1.0.0
+host = 0.0.0.0
+port = 8000
+docs_enabled = false
+
+[fastapi]
+workers = 4
+log_level = warning
+app_import = my_service.app:server
+
+[api]
+cors_origins = https://app.example.com
+```
+
+**What is `app_import`?**
+
+When running multiple workers, uvicorn forks child processes that each need to reconstruct the app independently. They can't share the in-memory object from the parent process — they need an import path to build their own copy.
+
+`app_import` is `module.path:variable_name` where `variable_name` is whatever you assigned `VsServerFactory.get()` to:
+
+```python
+# my_service/app.py
+server = VsServerFactory.get("fastapi", config)  # → app_import = my_service.app:server
+server.run()
+```
+
+If `app_import` is not set, vs-server will attempt to auto-detect it and log it at startup. Copy the logged value into your config to make it explicit.
+
+**Custom server implementations** follow the same pattern — add a `[my_framework]` section in `config.ini` for any framework-specific keys and read them in your `VsServer` subclass.
+
 **`config.ini` example:**
 
 ```ini
@@ -469,6 +515,57 @@ async def get_report():
 
 ---
 
+## Request and Response Models
+
+All request bodies and response models must be Pydantic models — not SQLAlchemy entities or plain dicts. This is a hard requirement of FastAPI and applies to all server implementations built on vs-server.
+
+```python
+from pydantic import BaseModel
+
+class UserRequest(BaseModel):
+    name: str
+    email: str
+
+class UserResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+
+    model_config = {"from_attributes": True}
+```
+
+The mapping between your SQLAlchemy entity and your Pydantic schema is your responsibility:
+
+```
+Request (Pydantic) → Service → Entity (SQLAlchemy) → DB
+DB → Entity (SQLAlchemy) → Service → Response (Pydantic)
+```
+
+Never pass a SQLAlchemy entity as `response_model` — FastAPI will reject it at startup. Never return a SQLAlchemy entity directly from a route — serialize it first.
+
+Keeping schemas separate from entities is intentional: the DB schema and API schema can evolve independently, and sensitive fields (e.g. `password`) are excluded from responses by default.
+
+### @model — Reduce Schema Boilerplate (requires vs-db)
+
+If you are using `vs-db`, the `@model` decorator derives Pydantic fields directly from a SQLAlchemy entity so you don't repeat type definitions. Nullable columns become `Optional[T] = None` automatically. Fields already defined on the class are never overridden.
+
+```python
+from pydantic import BaseModel, Field
+from vs_db.decorator.vs_model_decorator import model
+
+@model(AppUser, exclude=["password"])
+class UserResponse(BaseModel):
+    pass  # all AppUser fields injected except password
+
+@model(AppUser, include=["email", "first_name", "last_name"])
+class CreateUserRequest(BaseModel):
+    first_name: str = Field(min_length=1)  # user-defined — decorator skips it
+```
+
+See the `vs-db` README for full documentation on `@model`.
+
+---
+
 ## HTTP Controllers
 
 Annotate a class with `@controller` and methods with HTTP verb decorators.
@@ -520,11 +617,11 @@ All FastAPI route parameters (`response_model`, `status_code`, `tags`, `summary`
 
 | Decorator | HTTP Method |
 |---|---|
-| `@get(path, guards=[], **kwargs)` | GET |
-| `@post(path, guards=[], **kwargs)` | POST |
-| `@put(path, guards=[], **kwargs)` | PUT |
-| `@delete(path, guards=[], **kwargs)` | DELETE |
-| `@patch(path, guards=[], **kwargs)` | PATCH |
+| `@get(path, summary, description, guards=[], **kwargs)` | GET |
+| `@post(path, summary, description, guards=[], **kwargs)` | POST |
+| `@put(path, summary, description, guards=[], **kwargs)` | PUT |
+| `@delete(path, summary, description, guards=[], **kwargs)` | DELETE |
+| `@patch(path, summary, description, guards=[], **kwargs)` | PATCH |
 
 Guards on a method are merged with controller-level guards — both run.
 
@@ -986,9 +1083,10 @@ Override template methods to customise behaviour:
 |---|---|---|
 | `get_host()` | Reads `server.host` | Hard-code or compute the bind address |
 | `get_port()` | Reads `server.port` | Hard-code or compute the bind port |
-| `get_reload()` | Reads `server.reload` | Force hot-reload on/off |
-| `get_workers()` | Reads `server.workers` | Set worker count programmatically |
-| `get_log_level()` | Reads `server.log_level` | Set log level programmatically |
+| `get_reload()` | FastAPI only — reads `fastapi.reload` | Force hot-reload on/off |
+| `get_workers()` | FastAPI only — reads `fastapi.workers` | Set worker count programmatically |
+| `get_log_level()` | FastAPI only — reads `fastapi.log_level` | Set log level programmatically |
+| `get_app_import()` | FastAPI only — reads `fastapi.app_import` | Return import string for multi-worker mode |
 | `get_ssl_certfile()` | Reads `server.ssl_certfile` | Load cert from a secret store |
 | `get_ssl_keyfile()` | Reads `server.ssl_keyfile` | Load key from a secret store |
 | `get_ssl_keyfile_password()` | Reads `server.ssl_keyfile_password` | Load password from a secret store |
@@ -1164,8 +1262,10 @@ Route decorators. Applied to methods inside a `@controller` class.
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `path` | `str` | No | `""` | Route path appended to the controller prefix |
+| `summary` | `str` | No | `None` | Short one-line description shown in Swagger |
+| `description` | `str` | No | `None` | Longer description shown in Swagger |
 | `guards` | `List[Callable]` | No | `[]` | Merged with controller guards |
-| `**kwargs` | — | No | — | Passed to the underlying FastAPI route decorator (e.g. `response_model`, `status_code`, `summary`) |
+| `**kwargs` | — | No | — | Passed to the underlying FastAPI route decorator (e.g. `response_model`, `status_code`) |
 
 ---
 

vs_server-0.1.2/vs_server/decorator/vs_controller_decorator.py

@@ -1,44 +0,0 @@
-from typing import Callable, List, Type
-
-
-def controller(path: str, description: str = "", guards: List[Callable] = None):
-    def decorator(cls: Type) -> Type:
-        cls._vs_controller = {
-            "path": path,
-            "description": description,
-            "guards": guards or [],
-        }
-        return cls
-    return decorator
-
-
-def _route(method: str, path: str = "", guards: List[Callable] = None, **kwargs):
-    def decorator(fn: Callable) -> Callable:
-        fn._vs_route = {
-            "method": method,
-            "path": path,
-            "guards": guards or [],
-            "kwargs": kwargs,
-        }
-        return fn
-    return decorator
-
-
-def get(path: str = "", guards: List[Callable] = None, **kwargs):
-    return _route("GET", path, guards=guards, **kwargs)
-
-
-def post(path: str = "", guards: List[Callable] = None, **kwargs):
-    return _route("POST", path, guards=guards, **kwargs)
-
-
-def put(path: str = "", guards: List[Callable] = None, **kwargs):
-    return _route("PUT", path, guards=guards, **kwargs)
-
-
-def delete(path: str = "", guards: List[Callable] = None, **kwargs):
-    return _route("DELETE", path, guards=guards, **kwargs)
-
-
-def patch(path: str = "", guards: List[Callable] = None, **kwargs):
-    return _route("PATCH", path, guards=guards, **kwargs)