jac-scale 0.1.0__tar.gz

jac_scale-0.1.0/PKG-INFO

@@ -0,0 +1,658 @@
+Metadata-Version: 2.4
+Name: jac-scale
+Version: 0.1.0
+Author-email: Jason Mars <jason@mars.ninja>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: jaclang>=0.9.9
+Requires-Dist: python-dotenv<2.0.0,>=1.2.1
+Requires-Dist: docker<8.0.0,>=7.1.0
+Requires-Dist: kubernetes<35.0.0,>=34.1.0
+Requires-Dist: pymongo<5.0.0,>=4.15.4
+Requires-Dist: redis<8.0.0,>=7.1.0
+Requires-Dist: fastapi<0.122.0,>=0.121.3
+Requires-Dist: uvicorn<0.39.0,>=0.38.0
+Requires-Dist: pyjwt
+Requires-Dist: fastapi-sso<1.0.0,>=0.18.0
+Requires-Dist: python-multipart<1.0.0,>=0.0.21
+
+# JAC Scale Deployment Guide
+
+## Overview
+
+`jac start --scale` is a comprehensive deployment and scaling solution for JAC applications that provides three powerful capabilities:
+
+### 1. Multi-Layer Memory Architecture
+
+- **Caching Layer**: Redis for high-speed data access and session management
+- **Persistence Storage**: MongoDB for reliable, long-term data storage
+- **Optimized Performance**: Intelligent caching strategy to minimize database load and maximize response times
+
+### 2. FastAPI Integration with Swagger Documentation
+
+- Automatically converts JAC walkers and functions into RESTful FastAPI endpoints
+- Built-in Swagger/OpenAPI documentation for easy API exploration and testing
+- Interactive API interface accessible at `/docs` endpoint
+
+### 3. Kubernetes Deployment & Auto-Scaling
+
+- **Easy Deployment**: One-command deployment to Kubernetes clusters
+- **Auto-Scaling**: Scale your application based on demand
+- **Database Auto-Provisioning**: Automatically spawns and configures Redis and MongoDB instances
+- **Production-Ready**: Built-in health checks, persistent storage, and service discovery
+
+Whether you're developing locally with `jac start` or deploying to production with `jac start --scale`, you get the same powerful features with the flexibility to choose your deployment strategy.
+
+## Prerequisites
+
+- kubenetes(K8s) installed
+  - [Minikube Kubernetes](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fwindows%2Fx86-64%2Fstable%2F.exe+download/) (for Windows/Linux)
+  - [Docker Desktop with Kubernetes](https://www.docker.com/resources/kubernetes-and-docker/) (alternative for Windows - easier setup)
+
+**Note:** Kubernetes is only needed if you are planning to use `jac start --scale`. If you only want to use `jac start`, Kubernetes is not required.
+
+## Quick Start: Running the Travel Planner Demo Application
+
+Follow these steps to set up and test the Travel Planner JAC application
+
+### 1. Clone the Jaseci Repository
+
+First, clone the main Jaseci repository which contains JAC and JAC-Scale:
+
+```bash
+git clone https://github.com/jaseci-labs/jaseci.git
+cd jaseci
+git submodule update --init --recursive
+```
+
+### 2. Create Python Virtual Environment
+
+```bash
+python -m venv venv
+```
+
+### 3. Activate the Virtual Environment
+
+**Linux/Mac:**
+
+```bash
+source venv/bin/activate
+```
+
+**Windows:**
+
+```bash
+venv\Scripts\activate
+```
+
+### 4. Install JAC and JAC-Scale
+
+Install both packages in editable mode from the cloned repository:
+
+```bash
+pip install -e ./jac
+pip install -e ./jac-scale
+```
+
+### 5. Download the Demo Application
+
+Download the Travel Planner demo application from GitHub:
+
+**Option A: Using Git Clone (Recommended)**
+
+```bash
+# Navigate back to parent directory or choose a location
+cd ..
+
+# Clone the entire repository
+git clone https://github.com/jaseci-labs/Agentic-AI.git
+
+# Navigate to the Travel Planner backend and rename
+mv Agentic-AI/Travel_planner/BE traveller
+cd traveller
+```
+
+**Option B: Download Specific Folder**
+
+If you only want the Travel Planner backend:
+
+```bash
+# Navigate back to parent directory
+cd ..
+
+# Install GitHub CLI if not already installed
+# For Linux/Mac with Homebrew:
+brew install gh
+
+# For Windows with Chocolatey:
+choco install gh
+
+# Clone only the specific folder
+gh repo clone jaseci-labs/Agentic-AI
+mv Agentic-AI/Travel_planner/BE traveller
+cd traveller
+```
+
+**Option C: Manual Download**
+
+1. Go to https://github.com/jaseci-labs/Agentic-AI/tree/main/Travel_planner/BE
+2. Click on the green "Code" button
+3. Select "Download ZIP"
+4. Extract the ZIP file
+5. Rename the `BE` folder to `traveller`
+6. Navigate into the folder:
+
+```bash
+cd traveller
+```
+
+### 6. Configure Environment Variables
+
+You should now be in the `traveller` folder. Create a `.env` file:
+
+```bash
+# Verify you're in the correct directory
+pwd  # Should show path ending in /traveller
+
+# Create .env file
+touch .env  # Linux/Mac
+# OR
+type nul > .env  # Windows CMD
+# OR
+New-Item .env  # Windows PowerShell
+```
+
+Add the following to your `.env` file:
+
+```env
+OPENAI_API_KEY=your-openai-api-key-here
+```
+
+### 7. Install Demo Application Requirements
+
+```bash
+pip install byllm python-dotenv
+```
+
+### 8. Run the Application with JAC Start
+
+To run your application using FastAPI with ShelfStorage (no Kubernetes required):
+
+```bash
+jac start main.jac
+```
+
+**What this does:**
+
+- Starts your JAC application as a FastAPI server
+- Uses ShelfStorage for persisting anchors (lightweight, file-based storage)
+- No database setup required
+- Ideal for development and testing
+
+**Access your application:**
+
+- Application: http://localhost:8000
+- Swagger Documentation: http://localhost:8000/docs
+
+### 9. Set Up Kubernetes (For JAC Scale)
+
+To use `jac start --scale`, you need Kubernetes installed on your machine.
+
+**Option A: MicroK8s (Windows/Linux/Mac)**
+
+- [Official MicroK8s installation guide](https://microk8s.io/)
+- [ubunutu installation guide](https://www.digitalocean.com/community/tutorials/how-to-setup-a-microk8s-kubernetes-cluster-on-ubuntu-22-04)
+
+**Option B: Docker Desktop with Kubernetes (Windows - Recommended)**
+
+- Install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+- Enable Kubernetes in Docker Desktop settings (easier setup)
+
+### 10. Deploy with JAC Scale
+
+Once Kubernetes is running, you have two deployment methods:
+
+#### Method A: Deploy Without Building (Faster)
+
+Deploy your application to Kubernetes without building a Docker image:
+
+```bash
+jac start main.jac --scale
+```
+
+**What this does:**
+
+- Deploys your JAC application to Kubernetes
+- Automatically provisions Redis and MongoDB as persistence storage
+- Creates necessary Kubernetes resources (Deployments, Services, StatefulSets)
+- Exposes your application via NodePort
+
+**Access your application:**
+
+- Application: http://localhost:30001
+- Swagger Documentation: http://localhost:30001/docs
+
+**Use this when:**
+
+- You want faster deployments without rebuilding
+- You're testing configuration changes
+- You're in development mode
+
+#### Method B: Build, Push, and Deploy (Production)
+
+Build your application as a Docker container and deploy it:
+
+**Prerequisites:**
+
+1. Create a `Dockerfile` in your `traveller` directory
+2. Add Docker credentials to your `.env` file:
+
+```env
+OPENAI_API_KEY=your-openai-api-key-here
+DOCKER_USERNAME=your-dockerhub-username
+DOCKER_PASSWORD=your-dockerhub-password-or-token
+```
+
+**Deploy with build:**
+
+```bash
+jac start main.jac --scale --build
+```
+
+**What this does:**
+
+- Builds a Docker image of your JAC application
+- Pushes the image to DockerHub
+- Deploys the image to Kubernetes
+- Sets up Redis and MongoDB for persistence
+
+**Access your application:**
+
+- Application: http://localhost:30001
+- Swagger Documentation: http://localhost:30001/docs
+
+**Use this when:**
+
+- Deploying to production
+- You want to version and host your Docker image
+- Sharing your application with others
+- Creating reproducible deployments
+
+### 11. Clean Up Kubernetes Resources
+
+When you're done testing, remove all created Kubernetes resources:
+
+```bash
+jac destroy main.jac
+```
+
+**What this does:**
+
+- Deletes all Kubernetes deployments, services, and StatefulSets
+- Removes persistent volumes and claims
+- Cleans up the namespace (if custom namespace was used)
+
+## Quick Start: Running Todo application with frontend
+
+Follow these steps to set up and test the Todo application with frontend
+
+### 1. Clone the Jaseci Repository
+
+First, clone the main Jaseci repository which contains JAC and JAC-Scale:
+
+```bash
+git clone https://github.com/jaseci-labs/jaseci.git
+cd jaseci
+git submodule update --init --recursive
+```
+
+### 2. Create Python Virtual Environment
+
+```bash
+python -m venv venv
+```
+
+### 3. Activate the Virtual Environment
+
+**Linux/Mac:**
+
+```bash
+source venv/bin/activate
+```
+
+**Windows:**
+
+```bash
+venv\Scripts\activate
+```
+
+### 4. Install JAC, JAC-Scale and JAC-Client
+
+Install the packages in editable mode from the cloned repository:
+
+```bash
+pip install -e ./jac
+pip install -e ./jac-scale
+pip install -e ./jac-client
+```
+
+### 5. Create Todo application using jac-client
+
+Lets create the todo application using jac client.For that lets run following command
+
+```bash
+jac create_jac_app todo
+```
+
+Then lets copy the todo fully implemented jac code available inside jac-scale/examples/todo to our newly created /todo folder
+
+```bash
+cp jac-scale/examples/todo/app.jac todo/app.jac
+cd todo
+```
+
+### 8. Run the Application Locally
+
+To run your application run the following command
+
+```bash
+jac start app.jac
+```
+
+**Access your application:**
+
+- Frontend: http://localhost:8000/cl/app
+- Backend: http://localhost:8000
+- Swagger Documentation: http://localhost:8000/docs
+
+you can add new todo tasks
+ from the frontend at http://localhost:8000/cl/app
+
+### 9. Set Up Kubernetes (For JAC Scale)
+
+To use `jac start --scale`, you need Kubernetes installed on your machine.
+
+**Option A: MicroK8 (Windows/Linux/Mac)**
+
+- [Official MicroK8 installation guide](https://microk8s.io/)
+- [ubunutu installation guide](https://www.digitalocean.com/community/tutorials/how-to-setup-a-microk8s-kubernetes-cluster-on-ubuntu-22-04)
+
+**Option B: Docker Desktop with Kubernetes (Windows - Recommended)**
+
+- Install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+- Enable Kubernetes in Docker Desktop settings (easier setup)
+
+### 10. Deploy with JAC Scale
+
+Once Kubernetes is running, you have two deployment methods:
+
+#### Method A: Deploy Without Building (Faster)
+
+Deploy your application to Kubernetes without building a Docker image:
+
+```bash
+jac start app.jac --scale
+```
+
+**Access your application:**
+
+- Frontend: http://localhost:30001/cl/app
+- Backend: http://localhost:30001
+- Swagger Documentation: http://localhost:30001/docs
+
+**Use this when:**
+
+- You want faster deployments without rebuilding
+- You're testing configuration changes
+- You're in development mode
+
+#### Method B: Build, Push, and Deploy (Production)
+
+To Build your application as a Docker container and deploy it you can run
+
+```bash
+jac start app.jac --scale --build
+```
+
+**Access your application:**
+
+- Frontend: http://localhost:30001/cl/app
+- Backend: http://localhost:30001
+- Swagger Documentation: http://localhost:30001/docs
+
+**Use this when:**
+
+- Deploying to production
+- You want to version and host your Docker image
+- Sharing your application with others
+- Creating reproducible deployments
+
+### 11. Clean Up Kubernetes Resources
+
+When you're done testing, remove all created Kubernetes resources:
+
+```bash
+jac destroy app.jac
+```
+
+**What this does:**
+
+- Deletes all Kubernetes deployments, services, and StatefulSets
+- Removes persistent volumes and claims
+- Cleans up the namespace (if custom namespace was used)
+
+## Async Walkers
+
+JAC Scale supports async walkers for non-blocking operations like external API calls, database queries, and file I/O.
+
+```
+import asyncio;
+
+async walker FetchData {
+    has url: str;
+
+    async can fetch with `root entry {
+        report {"status": "fetching"};
+        await asyncio.sleep(0.1);  # Simulate API call
+        report {"status": "completed", "data": "result"};
+    }
+}
+```
+
+## Configuration Options
+
+### Optional Environment Variables
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `APP_NAME` | Name of your JAC application | `jaseci` |
+| `DOCKER_USERNAME` | DockerHub username for pushing the image | - |
+| `DOCKER_PASSWORD` | DockerHub password or access token | - |
+| `K8s_NAMESPACE` | Kubernetes namespace to deploy the application | `default` |
+| `K8s_NODE_PORT` | Port in which your local kubernetes application will run on| `30001` |
+| `K8s_CPU_REQUEST` | CPU request for the application container | - |
+| `K8s_CPU_LIMIT` | CPU limit for the application container | - |
+| `K8s_MEMORY_REQUEST` | Memory request for the application container | - |
+| `K8s_MEMORY_LIMIT` | Memory limit for the application container | - |
+| `K8s_READINESS_INITIAL_DELAY` | Seconds before readiness probe first checks the pod | `10` |
+| `K8s_READINESS_PERIOD` | Seconds between readiness probe checks | `20` |
+| `K8s_LIVENESS_INITIAL_DELAY` | Seconds before liveness probe first checks the pod | `10` |
+| `K8s_LIVENESS_PERIOD` | Seconds between liveness probe checks | `20` |
+| `K8s_LIVENESS_FAILURE_THRESHOLD` | Consecutive liveness probe failures before restart | `80` |
+| `K8s_MONGODB` | Whether MongoDB is needed (`True`/`False`) | `True` |
+| `K8s_REDIS` | Whether Redis is needed (`True`/`False`) | `True` |
+| `MONGODB_URI` | URL of MongoDB database | - |
+| `REDIS_URL` | URL of Redis database | - |
+| `JWT_EXP_DELTA_DAYS` | Number of days until JWT token expires | `7` |
+| `JWT_SECRET` | Secret key used for JWT token signing and verification | `'supersecretkey'` |
+| `JWT_ALGORITHM` | Algorithm used for JWT token encoding/decoding | `'HS256'` |
+| `SSO_HOST` | SSO host URL | `'http://localhost:8000/sso'` |
+| `SSO_GOOGLE_CLIENT_ID` | Google OAuth client ID | - |
+| `SSO_GOOGLE_CLIENT_SECRET` | Google OAuth client secret | - |
+
+## Deployment Modes
+
+### Mode 1: Deploy Without Building (Default)
+
+Deploys your JAC application to Kubernetes without building a Docker image.
+
+```bash
+jac start main.jac --scale
+```
+
+**Use this when:**
+
+- You want faster deployments without rebuilding
+- You're testing configuration changes
+- You're in development mode
+
+### Mode 2: Build, Push, and Deploy
+
+Builds a new Docker image, pushes it to DockerHub, then deploys to Kubernetes.
+
+```bash
+jac start main.jac --scale --build
+```
+
+**Requirements for Build Mode:**
+
+- A `Dockerfile` in your application directory
+- Environment variables set:
+  - `DOCKER_USERNAME` - Your DockerHub username
+  - `DOCKER_PASSWORD` - Your DockerHub password/access token
+
+**Use this when:**
+
+- Deploying to production
+- You want to version and host your Docker image
+- Sharing your application with others
+
+## Important Notes
+
+### Implementation
+
+- The jac-scale plugin is implemented using **Python and Kubernetes Python client libraries**
+- **No custom Kubernetes controllers** are used → easier to deploy and maintain
+
+### Database Provisioning
+
+- Databases are created as **StatefulSets** with persistent storage
+- Databases are **only created on the first run**
+- Subsequent `jac start --scale` calls only update application deployments
+- This ensures persistent storage and avoids recreating databases unnecessarily
+
+### Performance
+
+- **First-time deployment** may take longer due to database provisioning and image downloading
+- **Subsequent deployments** are faster since:
+  - Only the application's final Docker layer is pushed and pulled
+  - Only deployments are updated (databases remain unchanged)
+
+## Deployment Process
+
+When you run `jac start --scale`, the following steps are executed:
+
+### 1. Create JAC Application Docker Image
+
+- Build the application image from the source directory
+- Tag the image with DockerHub repository
+
+### 2. Push Docker Image to DockerHub (Build Mode Only)
+
+- Authenticate using `DOCKER_USERNAME` and `DOCKER_PASSWORD`
+- Push the image to DockerHub
+- Subsequent pushes are faster since only the final image layer is pushed
+
+### 3. Deploy to Kubernetes
+
+- Create or update Kubernetes namespace
+- Deploy Redis and MongoDB (first run only)
+- Create application deployment
+- Create services and expose via NodePort
+
+## Architecture
+
+### K8s pods structure
+
+![K8s pod structure](assets/jac-scale-architecture.svg)
+
+## Troubleshooting
+
+### Common Issues
+
+**Kubernetes cluster not accessible:**
+
+- Ensure Kubernetes is running: `kubectl cluster-info`
+- Check your kubeconfig: `kubectl config view`
+
+**DockerHub authentication fails:**
+
+- Verify your `DOCKER_USERNAME` and `DOCKER_PASSWORD` are correct
+- Ensure you're using an access token (not password) if 2FA is enabled
+
+**Namespace doesn't exist:**
+
+- The plugin creates namespaces automatically
+- If using a custom namespace, ensure proper permissions
+
+**Database connection issues:**
+
+- Verify StatefulSets are running: `kubectl get statefulsets -n <namespace>`
+- Check pod logs: `kubectl logs <pod-name> -n <namespace>`
+- Ensure persistent volumes are bound: `kubectl get pvc -n <namespace>`
+
+**Application not accessible:**
+
+- Check service exposure: `kubectl get svc -n <namespace>`
+- Verify NodePort is not blocked by firewall
+- For Minikube, use: `minikube service <service-name> -n <namespace>`
+
+**Build failures:**
+
+- Ensure Dockerfile exists in your application directory
+- Check Docker daemon is running
+- Verify sufficient disk space for image building
+
+### Getting Help
+
+If you encounter issues:
+
+1. Check pod status: `kubectl get pods -n <namespace>`
+2. View pod logs: `kubectl logs <pod-name> -n <namespace>`
+3. Describe resources: `kubectl describe <resource-type> <resource-name> -n <namespace>`
+
+## Tested Examples
+
+You can find more working examples in the examples directory:
+
+<!-- - [basic](../jac-client/jac_client/examples/basic/) - Minimal JAC application -->
+<!-- - [basic-full-stack](../jac-client/jac_client/examples/basic-full-stack/) - Basic full-stack application -->
+- [all-in-one](../jac-client/jac_client/examples/all-in-one/) - Complete example with all features
+- [with-router](../jac-client/jac_client/examples/with-router/) - Application with routing
+<!-- - [nested-folders/nested-basic](../jac-client/jac_client/examples/nested-folders/nested-basic/) - Basic nested folder structure -->
+- [nested-folders/nested-advance](../jac-client/jac_client/examples/nested-folders/nested-advance/) - Advanced nested folder structure
+- [basic-auth](../jac-client/jac_client/examples/basic-auth/) - Basic authentication
+- [basic-auth-with-router](../jac-client/jac_client/examples/basic-auth-with-router/) - Authentication with routing
+<!-- - [full-stack-with-auth](../jac-client/jac_client/examples/full-stack-with-auth/) - Full-stack app with authentication -->
+- [css-styling/js-styling](../jac-client/jac_client/examples/css-styling/js-styling/) - JavaScript styling example
+- [css-styling/material-ui](../jac-client/jac_client/examples/css-styling/material-ui/) - Material-UI styling example
+- [css-styling/pure-css](../jac-client/jac_client/examples/css-styling/pure-css/) - Pure CSS styling example
+- [css-styling/sass-example](../jac-client/jac_client/examples/css-styling/sass-example/) - SASS styling example
+- [css-styling/styled-components](../jac-client/jac_client/examples/css-styling/styled-components/) - Styled Components example
+- [css-styling/tailwind-example](../jac-client/jac_client/examples/css-styling/tailwind-example/) - Tailwind CSS example
+- [asset-serving/css-with-image](../jac-client/jac_client/examples/asset-serving/css-with-image/) - CSS with image assets
+- [asset-serving/image-asset](../jac-client/jac_client/examples/asset-serving/image-asset/) - Image asset serving
+- [asset-serving/import-alias](../jac-client/jac_client/examples/asset-serving/import-alias/) - Import alias example
+<!-- - [little-x](../jac-client/jac_client/examples/little-x/) - Little X application example -->
+
+Each example includes complete source code and can be run with `jac start`.
+
+## Next Steps
+
+After successfully running the demo:
+
+- **For local development (`jac start`)**: Access your application at http://localhost:8000 and explore the Swagger documentation at http://localhost:8000/docs
+- **For Kubernetes (`jac start --scale`)**: Access your application at http://localhost:30001 and explore the Swagger documentation at http://localhost:30001/docs
+- Modify the JAC application and redeploy
+- Experiment with different configuration options
+- Try deploying to a production Kubernetes cluster