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.
- viveka_setu-0.1.0/LICENSE.txt +86 -0
- viveka_setu-0.1.0/PKG-INFO +355 -0
- viveka_setu-0.1.0/README.md +232 -0
- viveka_setu-0.1.0/pyproject.toml +55 -0
- viveka_setu-0.1.0/setup.cfg +4 -0
- viveka_setu-0.1.0/viveka_server/__init__.py +37 -0
- viveka_setu-0.1.0/viveka_server/app/__init__.py +3 -0
- viveka_setu-0.1.0/viveka_server/app/viveka_app.py +80 -0
- viveka_setu-0.1.0/viveka_server/py.typed +0 -0
- viveka_setu-0.1.0/viveka_server/schema/__init__.py +33 -0
- viveka_setu-0.1.0/viveka_server/schema/exceptions.py +217 -0
- viveka_setu-0.1.0/viveka_server/schema/viveka_app_config.py +11 -0
- viveka_setu-0.1.0/viveka_server/schema/viveka_server_health.py +12 -0
- viveka_setu-0.1.0/viveka_server/server/__init__.py +3 -0
- viveka_setu-0.1.0/viveka_server/server/viveka_server.py +238 -0
- viveka_setu-0.1.0/viveka_setu.egg-info/PKG-INFO +355 -0
- viveka_setu-0.1.0/viveka_setu.egg-info/SOURCES.txt +18 -0
- viveka_setu-0.1.0/viveka_setu.egg-info/dependency_links.txt +1 -0
- viveka_setu-0.1.0/viveka_setu.egg-info/requires.txt +15 -0
- viveka_setu-0.1.0/viveka_setu.egg-info/top_level.txt +1 -0
|
@@ -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/)
|