viveka-setu 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,86 @@
1
+ VIVEKASUTRA PROPRIETARY SOFTWARE LICENSE
2
+
3
+ Copyright (c) 2025 VivekaSutra. All rights reserved.
4
+ https://vivekasutra.com/
5
+
6
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
7
+ IMPORTANT: READ THIS LICENSE CAREFULLY BEFORE DOWNLOADING,
8
+ INSTALLING, OR USING THIS SOFTWARE.
9
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
10
+
11
+ By downloading, installing, or using this software ("viveka-setu"),
12
+ you agree to be bound by the terms of this license agreement.
13
+ If you do not agree, do not download, install, or use this software.
14
+
15
+
16
+ 1. GRANT OF LICENSE
17
+ VivekaSutra grants you a limited, non-exclusive, non-transferable,
18
+ royalty-free license to download and use this software solely for
19
+ your personal or internal business purposes.
20
+
21
+
22
+ 2. RESTRICTIONS
23
+ You may NOT:
24
+ a) Copy, modify, merge, or create derivative works of this software.
25
+ b) Distribute, sell, sublicense, rent, lease, or transfer this
26
+ software or any rights in it to any third party.
27
+ c) Reverse engineer, decompile, disassemble, or attempt to derive
28
+ the source code of this software.
29
+ d) Remove, alter, or obscure any proprietary notices, labels,
30
+ or markings on this software.
31
+ e) Use this software to build a competing product or service.
32
+
33
+
34
+ 3. INTELLECTUAL PROPERTY
35
+ This software and all copies thereof are proprietary to VivekaSutra.
36
+ All title, ownership rights, and intellectual property rights remain
37
+ exclusively with VivekaSutra. This license does not grant you any
38
+ rights to trademarks, service marks, or trade names of VivekaSutra.
39
+
40
+
41
+ 4. NO WARRANTY
42
+ THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
43
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
44
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
45
+ NON-INFRINGEMENT.
46
+
47
+ VIVEKASUTRA DOES NOT WARRANT THAT:
48
+ a) THE SOFTWARE WILL MEET YOUR REQUIREMENTS.
49
+ b) THE SOFTWARE WILL OPERATE UNINTERRUPTED OR ERROR-FREE.
50
+ c) ANY ERRORS IN THE SOFTWARE WILL BE CORRECTED.
51
+ d) THE SOFTWARE IS COMPATIBLE WITH YOUR SYSTEMS OR ENVIRONMENT.
52
+
53
+ YOU ASSUME ALL RISK ASSOCIATED WITH THE USE OF THIS SOFTWARE.
54
+
55
+
56
+ 5. LIMITATION OF LIABILITY
57
+ TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
58
+ VIVEKASUTRA, ITS DIRECTORS, EMPLOYEES, PARTNERS, AGENTS, SUPPLIERS,
59
+ OR AFFILIATES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
60
+ EXEMPLARY, OR CONSEQUENTIAL DAMAGES INCLUDING BUT NOT LIMITED TO LOSS
61
+ OF PROFITS, DATA, BUSINESS, OR GOODWILL, EVEN IF VIVEKASUTRA HAS BEEN
62
+ ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
63
+
64
+
65
+ 6. INDEMNIFICATION
66
+ You agree to indemnify and hold harmless VivekaSutra from and against
67
+ any claims, liabilities, damages, losses, and expenses arising out of
68
+ your use of this software or violation of this license.
69
+
70
+
71
+ 7. TERMINATION
72
+ Your rights under this license terminate automatically if you fail to
73
+ comply with any of its terms. Upon termination you must immediately
74
+ cease all use and destroy all copies in your possession.
75
+
76
+
77
+ 8. GOVERNING LAW
78
+ This license shall be governed by applicable laws. Disputes shall be
79
+ subject to the exclusive jurisdiction of competent courts.
80
+
81
+
82
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
83
+ For licensing inquiries: https://vivekasutra.com/
84
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
85
+
86
+ VivekaSutra — Copyright (c) 2025. All rights reserved.
@@ -0,0 +1,355 @@
1
+ Metadata-Version: 2.4
2
+ Name: viveka-setu
3
+ Version: 0.1.0
4
+ Summary: FastAPI + Uvicorn application factory for Viveka services — built-in health, CORS, exception handling, and lifecycle management
5
+ License: VIVEKASUTRA PROPRIETARY SOFTWARE LICENSE
6
+
7
+ Copyright (c) 2025 VivekaSutra. All rights reserved.
8
+ https://vivekasutra.com/
9
+
10
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
11
+ IMPORTANT: READ THIS LICENSE CAREFULLY BEFORE DOWNLOADING,
12
+ INSTALLING, OR USING THIS SOFTWARE.
13
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
14
+
15
+ By downloading, installing, or using this software ("viveka-setu"),
16
+ you agree to be bound by the terms of this license agreement.
17
+ If you do not agree, do not download, install, or use this software.
18
+
19
+
20
+ 1. GRANT OF LICENSE
21
+ VivekaSutra grants you a limited, non-exclusive, non-transferable,
22
+ royalty-free license to download and use this software solely for
23
+ your personal or internal business purposes.
24
+
25
+
26
+ 2. RESTRICTIONS
27
+ You may NOT:
28
+ a) Copy, modify, merge, or create derivative works of this software.
29
+ b) Distribute, sell, sublicense, rent, lease, or transfer this
30
+ software or any rights in it to any third party.
31
+ c) Reverse engineer, decompile, disassemble, or attempt to derive
32
+ the source code of this software.
33
+ d) Remove, alter, or obscure any proprietary notices, labels,
34
+ or markings on this software.
35
+ e) Use this software to build a competing product or service.
36
+
37
+
38
+ 3. INTELLECTUAL PROPERTY
39
+ This software and all copies thereof are proprietary to VivekaSutra.
40
+ All title, ownership rights, and intellectual property rights remain
41
+ exclusively with VivekaSutra. This license does not grant you any
42
+ rights to trademarks, service marks, or trade names of VivekaSutra.
43
+
44
+
45
+ 4. NO WARRANTY
46
+ THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
47
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
48
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
49
+ NON-INFRINGEMENT.
50
+
51
+ VIVEKASUTRA DOES NOT WARRANT THAT:
52
+ a) THE SOFTWARE WILL MEET YOUR REQUIREMENTS.
53
+ b) THE SOFTWARE WILL OPERATE UNINTERRUPTED OR ERROR-FREE.
54
+ c) ANY ERRORS IN THE SOFTWARE WILL BE CORRECTED.
55
+ d) THE SOFTWARE IS COMPATIBLE WITH YOUR SYSTEMS OR ENVIRONMENT.
56
+
57
+ YOU ASSUME ALL RISK ASSOCIATED WITH THE USE OF THIS SOFTWARE.
58
+
59
+
60
+ 5. LIMITATION OF LIABILITY
61
+ TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
62
+ VIVEKASUTRA, ITS DIRECTORS, EMPLOYEES, PARTNERS, AGENTS, SUPPLIERS,
63
+ OR AFFILIATES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
64
+ EXEMPLARY, OR CONSEQUENTIAL DAMAGES INCLUDING BUT NOT LIMITED TO LOSS
65
+ OF PROFITS, DATA, BUSINESS, OR GOODWILL, EVEN IF VIVEKASUTRA HAS BEEN
66
+ ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
67
+
68
+
69
+ 6. INDEMNIFICATION
70
+ You agree to indemnify and hold harmless VivekaSutra from and against
71
+ any claims, liabilities, damages, losses, and expenses arising out of
72
+ your use of this software or violation of this license.
73
+
74
+
75
+ 7. TERMINATION
76
+ Your rights under this license terminate automatically if you fail to
77
+ comply with any of its terms. Upon termination you must immediately
78
+ cease all use and destroy all copies in your possession.
79
+
80
+
81
+ 8. GOVERNING LAW
82
+ This license shall be governed by applicable laws. Disputes shall be
83
+ subject to the exclusive jurisdiction of competent courts.
84
+
85
+
86
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
87
+ For licensing inquiries: https://vivekasutra.com/
88
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
89
+
90
+ VivekaSutra — Copyright (c) 2025. All rights reserved.
91
+
92
+ Project-URL: Homepage, https://vivekasutra.com/
93
+ Project-URL: Source, https://github.com/vivekasutra/viveka-setu
94
+ Keywords: fastapi,uvicorn,server,api,async,viveka,framework
95
+ Classifier: Development Status :: 3 - Alpha
96
+ Classifier: Intended Audience :: Developers
97
+ Classifier: License :: Other/Proprietary License
98
+ Classifier: Programming Language :: Python :: 3.11
99
+ Classifier: Programming Language :: Python :: 3.12
100
+ Classifier: Programming Language :: Python :: 3.13
101
+ Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
102
+ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
103
+ Classifier: Framework :: AsyncIO
104
+ Classifier: Framework :: FastAPI
105
+ Classifier: Typing :: Typed
106
+ Requires-Python: >=3.11
107
+ Description-Content-Type: text/markdown
108
+ License-File: LICENSE.txt
109
+ Requires-Dist: fastapi>=0.109
110
+ Requires-Dist: uvicorn[standard]>=0.27
111
+ Requires-Dist: starlette>=0.35
112
+ Requires-Dist: pydantic>=2.0
113
+ Requires-Dist: viveka-grantha>=0.1.0
114
+ Provides-Extra: database
115
+ Requires-Dist: viveka-kosha>=0.1.0; extra == "database"
116
+ Provides-Extra: dev
117
+ Requires-Dist: build; extra == "dev"
118
+ Requires-Dist: twine; extra == "dev"
119
+ Requires-Dist: pytest>=8.0; extra == "dev"
120
+ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
121
+ Requires-Dist: httpx>=0.27; extra == "dev"
122
+ Dynamic: license-file
123
+
124
+ # viveka-setu
125
+
126
+ FastAPI + Uvicorn application factory for Viveka services. Spin up a production-ready API server with built-in health checks, CORS, exception handling, DB middleware, and lifecycle management — in under ten lines of code.
127
+
128
+ Developed by [VivekaSutra](https://vivekasutra.com/)
129
+
130
+ ---
131
+
132
+ ## Overview
133
+
134
+ viveka-setu is the equivalent of Spring Boot's embedded Tomcat + `@SpringBootApplication`. It wraps FastAPI and Uvicorn so developers focus on business logic, not server boilerplate.
135
+
136
+ | Feature | Detail |
137
+ |---|---|
138
+ | Built-in routes | `GET /` (status) and `GET /health` (uptime + version) |
139
+ | CORS | Configurable origins via `config.ini` or defaults to `*` |
140
+ | Exception handling | Standard JSON error responses for all HTTP error types |
141
+ | DB middleware | Auto-wired `DbMiddleware` when `enable_database=True` |
142
+ | Cache | Auto-wired Redis cache when `enable_cache=True` |
143
+ | Lifecycle hooks | `startup()` and `shutdown()` overridable in `VivekaApp` |
144
+ | CLI args | `--host`, `--port`, `--reload`, `--workers`, `--log-level` |
145
+ | Config priority | CLI args → `config.ini` → hardcoded defaults |
146
+
147
+ ---
148
+
149
+ ## Installation
150
+
151
+ ```bash
152
+ pip install viveka-setu
153
+ ```
154
+
155
+ With database support (viveka-kosha):
156
+
157
+ ```bash
158
+ pip install "viveka-setu[database]"
159
+ ```
160
+
161
+ ---
162
+
163
+ ## Quickstart
164
+
165
+ ```python
166
+ from viveka_server import VivekaApp, VivekaServer, VivekaAppConfig
167
+
168
+ app = VivekaApp(VivekaAppConfig(name="my-service", version="1.0.0"))
169
+ server = VivekaServer(app)
170
+ server.run()
171
+ ```
172
+
173
+ That's it. Your service is running at `http://127.0.0.1:8000` with:
174
+ - `GET /` → `{"service": "my-service", "version": "1.0.0", "status": "running"}`
175
+ - `GET /health` → uptime, name, version, timestamp
176
+ - `GET /docs` → FastAPI Swagger UI
177
+
178
+ ---
179
+
180
+ ## Configuration
181
+
182
+ `config.ini`:
183
+
184
+ ```ini
185
+ [server]
186
+ host = 0.0.0.0
187
+ port = 8080
188
+ reload = false
189
+ workers = 4
190
+ log_level = info
191
+
192
+ [api]
193
+ cors_origins = https://myapp.com, https://admin.myapp.com
194
+
195
+ [logging]
196
+ level = INFO
197
+ file_path = logs/service.log
198
+
199
+ [database]
200
+ url = postgresql+asyncpg://user:pass@localhost/mydb
201
+ pool_size = 10
202
+ max_overflow = 20
203
+
204
+ [cache]
205
+ enabled = true
206
+ url = redis://localhost:6379/0
207
+ default_ttl = 3600
208
+ ```
209
+
210
+ ---
211
+
212
+ ## Adding Custom Routes
213
+
214
+ Override `build_routes()` in a `VivekaServer` subclass:
215
+
216
+ ```python
217
+ from fastapi import APIRouter
218
+ from viveka_server import VivekaApp, VivekaServer, VivekaAppConfig
219
+
220
+ class MyServer(VivekaServer):
221
+ def build_routes(self, router: APIRouter) -> APIRouter:
222
+
223
+ @router.get("/api/v1/ping")
224
+ async def ping():
225
+ return {"pong": True}
226
+
227
+ @router.get("/api/v1/users/{user_id}")
228
+ async def get_user(user_id: int):
229
+ return {"id": user_id}
230
+
231
+ return router
232
+
233
+ app = VivekaApp(VivekaAppConfig(name="my-service", version="1.0.0"))
234
+ server = MyServer(app)
235
+ server.run()
236
+ ```
237
+
238
+ ---
239
+
240
+ ## Lifecycle Hooks
241
+
242
+ Override `startup()` and `shutdown()` in a `VivekaApp` subclass for custom initialization:
243
+
244
+ ```python
245
+ from viveka_server import VivekaApp, VivekaAppConfig
246
+
247
+ class MyApp(VivekaApp):
248
+ async def startup(self) -> None:
249
+ await super().startup()
250
+ # load ML models, warm caches, connect external services
251
+ self.logger.info("Custom startup complete")
252
+
253
+ async def shutdown(self) -> None:
254
+ # release resources, flush buffers
255
+ self.logger.info("Custom shutdown complete")
256
+ await super().shutdown()
257
+ ```
258
+
259
+ ---
260
+
261
+ ## Enable Database & Cache
262
+
263
+ ```python
264
+ from viveka_server import VivekaApp, VivekaServer, VivekaAppConfig
265
+
266
+ app = VivekaApp(VivekaAppConfig(
267
+ name = "data-service",
268
+ version = "1.0.0",
269
+ enable_database = True, # auto-wires DbMiddleware + DatabaseSessionFactory
270
+ enable_cache = True, # auto-wires VivekaCacheManager + RedisCacheService
271
+ ))
272
+ server = VivekaServer(app)
273
+ server.run()
274
+ ```
275
+
276
+ Requires `[database]` and `[cache]` sections in `config.ini`.
277
+ Requires `pip install "viveka-setu[database]"` for DB support.
278
+
279
+ ---
280
+
281
+ ## Exception Handling
282
+
283
+ viveka-setu registers a global exception handler that converts all `VivekaAPIException` subclasses to a consistent JSON response:
284
+
285
+ ```json
286
+ {
287
+ "success": false,
288
+ "error": {
289
+ "code": "NOT_FOUND",
290
+ "message": "User not found",
291
+ "details": {}
292
+ }
293
+ }
294
+ ```
295
+
296
+ Raise exceptions directly from any route or service:
297
+
298
+ ```python
299
+ from viveka_server import NotFoundException, UnauthorizedException, RateLimitException
300
+
301
+ @router.get("/users/{user_id}")
302
+ async def get_user(user_id: int):
303
+ user = await user_repo.get(user_id)
304
+ if not user:
305
+ raise NotFoundException(f"User {user_id} not found")
306
+ return user
307
+ ```
308
+
309
+ ### Available Exceptions
310
+
311
+ | Class | HTTP Code | Error Code |
312
+ |---|---|---|
313
+ | `NotFoundException` | 404 | `NOT_FOUND` |
314
+ | `ValidationException` | 400 | `VALIDATION_ERROR` |
315
+ | `UnauthorizedException` | 401 | `UNAUTHORIZED` |
316
+ | `ForbiddenException` | 403 | `FORBIDDEN` |
317
+ | `InternalServerException` | 500 | `INTERNAL_ERROR` |
318
+ | `RateLimitException` | 429 | `RATE_LIMIT_EXCEEDED` |
319
+ | `BudgetExceededException` | 402 | `BUDGET_EXCEEDED` |
320
+ | `TimeoutException` | 504 | `TIMEOUT_ERROR` |
321
+ | `ProviderException` | 502 | `PROVIDER_ERROR` |
322
+
323
+ ---
324
+
325
+ ## CLI Usage
326
+
327
+ ```bash
328
+ python main.py --host 0.0.0.0 --port 8080 --workers 4
329
+ python main.py --reload # development mode
330
+ python main.py --log-level debug
331
+ ```
332
+
333
+ ---
334
+
335
+ ## Part of the Viveka Platform
336
+
337
+ - **viveka-grantha** — config, logging, cache (required)
338
+ - **viveka-kosha** — async database / ORM (optional, for `enable_database=True`)
339
+ - **viveka-setu** — server factory ← you are here
340
+
341
+ ---
342
+
343
+ ## License
344
+
345
+ Copyright (c) 2025 VivekaSutra. All rights reserved.
346
+
347
+ This software is distributed under the **VivekaSutra Proprietary Software License**.
348
+
349
+ - Free to download and use for personal or commercial purposes
350
+ - Modification, redistribution, and reverse engineering are not permitted
351
+ - Provided "AS IS" — no warranty of any kind
352
+ - VivekaSutra is not liable for any damages arising from use
353
+
354
+ See [LICENSE.txt](LICENSE.txt) for the full license text.
355
+ For licensing inquiries visit [vivekasutra.com](https://vivekasutra.com/)
@@ -0,0 +1,232 @@
1
+ # viveka-setu
2
+
3
+ FastAPI + Uvicorn application factory for Viveka services. Spin up a production-ready API server with built-in health checks, CORS, exception handling, DB middleware, and lifecycle management — in under ten lines of code.
4
+
5
+ Developed by [VivekaSutra](https://vivekasutra.com/)
6
+
7
+ ---
8
+
9
+ ## Overview
10
+
11
+ viveka-setu is the equivalent of Spring Boot's embedded Tomcat + `@SpringBootApplication`. It wraps FastAPI and Uvicorn so developers focus on business logic, not server boilerplate.
12
+
13
+ | Feature | Detail |
14
+ |---|---|
15
+ | Built-in routes | `GET /` (status) and `GET /health` (uptime + version) |
16
+ | CORS | Configurable origins via `config.ini` or defaults to `*` |
17
+ | Exception handling | Standard JSON error responses for all HTTP error types |
18
+ | DB middleware | Auto-wired `DbMiddleware` when `enable_database=True` |
19
+ | Cache | Auto-wired Redis cache when `enable_cache=True` |
20
+ | Lifecycle hooks | `startup()` and `shutdown()` overridable in `VivekaApp` |
21
+ | CLI args | `--host`, `--port`, `--reload`, `--workers`, `--log-level` |
22
+ | Config priority | CLI args → `config.ini` → hardcoded defaults |
23
+
24
+ ---
25
+
26
+ ## Installation
27
+
28
+ ```bash
29
+ pip install viveka-setu
30
+ ```
31
+
32
+ With database support (viveka-kosha):
33
+
34
+ ```bash
35
+ pip install "viveka-setu[database]"
36
+ ```
37
+
38
+ ---
39
+
40
+ ## Quickstart
41
+
42
+ ```python
43
+ from viveka_server import VivekaApp, VivekaServer, VivekaAppConfig
44
+
45
+ app = VivekaApp(VivekaAppConfig(name="my-service", version="1.0.0"))
46
+ server = VivekaServer(app)
47
+ server.run()
48
+ ```
49
+
50
+ That's it. Your service is running at `http://127.0.0.1:8000` with:
51
+ - `GET /` → `{"service": "my-service", "version": "1.0.0", "status": "running"}`
52
+ - `GET /health` → uptime, name, version, timestamp
53
+ - `GET /docs` → FastAPI Swagger UI
54
+
55
+ ---
56
+
57
+ ## Configuration
58
+
59
+ `config.ini`:
60
+
61
+ ```ini
62
+ [server]
63
+ host = 0.0.0.0
64
+ port = 8080
65
+ reload = false
66
+ workers = 4
67
+ log_level = info
68
+
69
+ [api]
70
+ cors_origins = https://myapp.com, https://admin.myapp.com
71
+
72
+ [logging]
73
+ level = INFO
74
+ file_path = logs/service.log
75
+
76
+ [database]
77
+ url = postgresql+asyncpg://user:pass@localhost/mydb
78
+ pool_size = 10
79
+ max_overflow = 20
80
+
81
+ [cache]
82
+ enabled = true
83
+ url = redis://localhost:6379/0
84
+ default_ttl = 3600
85
+ ```
86
+
87
+ ---
88
+
89
+ ## Adding Custom Routes
90
+
91
+ Override `build_routes()` in a `VivekaServer` subclass:
92
+
93
+ ```python
94
+ from fastapi import APIRouter
95
+ from viveka_server import VivekaApp, VivekaServer, VivekaAppConfig
96
+
97
+ class MyServer(VivekaServer):
98
+ def build_routes(self, router: APIRouter) -> APIRouter:
99
+
100
+ @router.get("/api/v1/ping")
101
+ async def ping():
102
+ return {"pong": True}
103
+
104
+ @router.get("/api/v1/users/{user_id}")
105
+ async def get_user(user_id: int):
106
+ return {"id": user_id}
107
+
108
+ return router
109
+
110
+ app = VivekaApp(VivekaAppConfig(name="my-service", version="1.0.0"))
111
+ server = MyServer(app)
112
+ server.run()
113
+ ```
114
+
115
+ ---
116
+
117
+ ## Lifecycle Hooks
118
+
119
+ Override `startup()` and `shutdown()` in a `VivekaApp` subclass for custom initialization:
120
+
121
+ ```python
122
+ from viveka_server import VivekaApp, VivekaAppConfig
123
+
124
+ class MyApp(VivekaApp):
125
+ async def startup(self) -> None:
126
+ await super().startup()
127
+ # load ML models, warm caches, connect external services
128
+ self.logger.info("Custom startup complete")
129
+
130
+ async def shutdown(self) -> None:
131
+ # release resources, flush buffers
132
+ self.logger.info("Custom shutdown complete")
133
+ await super().shutdown()
134
+ ```
135
+
136
+ ---
137
+
138
+ ## Enable Database & Cache
139
+
140
+ ```python
141
+ from viveka_server import VivekaApp, VivekaServer, VivekaAppConfig
142
+
143
+ app = VivekaApp(VivekaAppConfig(
144
+ name = "data-service",
145
+ version = "1.0.0",
146
+ enable_database = True, # auto-wires DbMiddleware + DatabaseSessionFactory
147
+ enable_cache = True, # auto-wires VivekaCacheManager + RedisCacheService
148
+ ))
149
+ server = VivekaServer(app)
150
+ server.run()
151
+ ```
152
+
153
+ Requires `[database]` and `[cache]` sections in `config.ini`.
154
+ Requires `pip install "viveka-setu[database]"` for DB support.
155
+
156
+ ---
157
+
158
+ ## Exception Handling
159
+
160
+ viveka-setu registers a global exception handler that converts all `VivekaAPIException` subclasses to a consistent JSON response:
161
+
162
+ ```json
163
+ {
164
+ "success": false,
165
+ "error": {
166
+ "code": "NOT_FOUND",
167
+ "message": "User not found",
168
+ "details": {}
169
+ }
170
+ }
171
+ ```
172
+
173
+ Raise exceptions directly from any route or service:
174
+
175
+ ```python
176
+ from viveka_server import NotFoundException, UnauthorizedException, RateLimitException
177
+
178
+ @router.get("/users/{user_id}")
179
+ async def get_user(user_id: int):
180
+ user = await user_repo.get(user_id)
181
+ if not user:
182
+ raise NotFoundException(f"User {user_id} not found")
183
+ return user
184
+ ```
185
+
186
+ ### Available Exceptions
187
+
188
+ | Class | HTTP Code | Error Code |
189
+ |---|---|---|
190
+ | `NotFoundException` | 404 | `NOT_FOUND` |
191
+ | `ValidationException` | 400 | `VALIDATION_ERROR` |
192
+ | `UnauthorizedException` | 401 | `UNAUTHORIZED` |
193
+ | `ForbiddenException` | 403 | `FORBIDDEN` |
194
+ | `InternalServerException` | 500 | `INTERNAL_ERROR` |
195
+ | `RateLimitException` | 429 | `RATE_LIMIT_EXCEEDED` |
196
+ | `BudgetExceededException` | 402 | `BUDGET_EXCEEDED` |
197
+ | `TimeoutException` | 504 | `TIMEOUT_ERROR` |
198
+ | `ProviderException` | 502 | `PROVIDER_ERROR` |
199
+
200
+ ---
201
+
202
+ ## CLI Usage
203
+
204
+ ```bash
205
+ python main.py --host 0.0.0.0 --port 8080 --workers 4
206
+ python main.py --reload # development mode
207
+ python main.py --log-level debug
208
+ ```
209
+
210
+ ---
211
+
212
+ ## Part of the Viveka Platform
213
+
214
+ - **viveka-grantha** — config, logging, cache (required)
215
+ - **viveka-kosha** — async database / ORM (optional, for `enable_database=True`)
216
+ - **viveka-setu** — server factory ← you are here
217
+
218
+ ---
219
+
220
+ ## License
221
+
222
+ Copyright (c) 2025 VivekaSutra. All rights reserved.
223
+
224
+ This software is distributed under the **VivekaSutra Proprietary Software License**.
225
+
226
+ - Free to download and use for personal or commercial purposes
227
+ - Modification, redistribution, and reverse engineering are not permitted
228
+ - Provided "AS IS" — no warranty of any kind
229
+ - VivekaSutra is not liable for any damages arising from use
230
+
231
+ See [LICENSE.txt](LICENSE.txt) for the full license text.
232
+ For licensing inquiries visit [vivekasutra.com](https://vivekasutra.com/)