# MGraph AI Service Cache Client
[](https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client/releases)
[](https://www.python.org/downloads/)
[](https://fastapi.tiangolo.com/)
[](https://aws.amazon.com/lambda/)
[](LICENSE)
[](https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client/actions)
A production-ready FastAPI microservice template for building MGraph-AI services. This template provides a complete scaffold with CI/CD pipeline, AWS Lambda deployment, and type-safe architecture.
## 🎯 Purpose
This repository serves as the base template for creating new MGraph-AI services. It includes:
- ✅ Complete FastAPI application structure
- ✅ Multi-stage CI/CD pipeline (dev, qa, prod)
- ✅ AWS Lambda deployment configuration
- ✅ Type-safe architecture using OSBot-Utils
- ✅ Comprehensive test coverage
- ✅ API key authentication
- ✅ Health check and monitoring endpoints
**Note**: This is a template repository. To create your own service, see [Creating Services from Template](docs/dev/non-functional-requirements/version-1_0_0/README.md).
## 📚 Creating a New Service
To create a new service from this template, see [Creating Services from MGraph-AI__Service__Cache__Client](docs/dev/non-functional-requirements/version-1_0_0/README.md).
## 🚀 Features
- **Type-Safe Architecture**: Built on OSBot-Utils type safety framework
- **Multi-Stage Deployment**: Automated CI/CD pipeline for dev, QA, and production
- **AWS Lambda Ready**: Optimized for serverless deployment
- **API Key Authentication**: Secure access control
## 📋 Table of Contents
- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [API Documentation](#-api-documentation)
- [Configuration](#-configuration)
- [Development](#-development)
- [Testing](#-testing)
- [Deployment](#-deployment)
- [Security](#-security)
- [Contributing](#-contributing)
- [License](#-license)
## 🎯 Quick Start
### Local Development
```bash
# Clone the repository
git clone https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client.git
cd MGraph-AI__Service__Cache__Client
# Install dependencies
pip install -r requirements-test.txt
pip install -e .
# Set environment variables
export FAST_API__AUTH__API_KEY__NAME="x-api-key"
export FAST_API__AUTH__API_KEY__VALUE="your-secret-key"
# Run locally
./scripts/run-locally.sh
# or
uvicorn mgraph_ai_service_cache__client.fast_api.lambda_handler:app --reload --host 0.0.0.0 --port 10011
```
### Basic Usage
```python
import requests
# Set up authentication
headers = {"x-api-key": "your-secret-key"}
base_url = "http://localhost:10011"
# Check service health
response = requests.get(f"{base_url}/health", headers=headers)
print(response.json())
# Get service info
response = requests.get(f"{base_url}/info/version", headers=headers)
print(response.json())
```
## 📦 Installation
### Prerequisites
- Python 3.12+
- AWS CLI (for deployment)
- Docker (for LocalStack testing)
### Using Poetry
```bash
# Install poetry if not already installed
pip install poetry
# Install dependencies
poetry install
# Activate virtual environment
poetry shell
```
### Using pip
```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements-test.txt
pip install -e .
```
## 📖 API Documentation
### Interactive API Documentation
Once the service is running, access the interactive API documentation at:
- Swagger UI: http://localhost:10011/docs
- ReDoc: http://localhost:10011/redoc
### Endpoints Overview
#### Health Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Service health check |
| `/health/detailed` | GET | Detailed health status |
#### Information Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/info/version` | GET | Get service version |
| `/info/status` | GET | Get service status |
## ⚙️ Configuration
### Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `FAST_API__AUTH__API_KEY__NAME` | Header name for API key | Yes | - |
| `FAST_API__AUTH__API_KEY__VALUE` | API key value | Yes | - |
| `AWS_REGION` | AWS region (triggers Lambda mode) | No | - |
| `DEBUG` | Enable debug logging | No | false |
### Configuration File
Create a `.env` file for local development:
```env
FAST_API__AUTH__API_KEY__NAME=x-api-key
FAST_API__AUTH__API_KEY__VALUE=development-key-12345
```
## 🛠️ Development
### Project Structure
```
mgraph_ai_service_cache__client/
├── fast_api/
│ ├── lambda_handler.py # AWS Lambda entry point
│ ├── Service__Fast_API.py # FastAPI application setup
│ └── routes/ # API endpoint definitions
├── service/
│ └── info/ # Service information
├── utils/
│ ├── deploy/ # Deployment utilities
│ └── Version.py # Version management
└── config.py # Service configuration
```
### Adding New Endpoints
1. Create a new route class in `fast_api/routes/`:
```python
from osbot_fast_api.api.Fast_API_Routes import Fast_API_Routes
class Routes__MyFeature(Fast_API_Routes):
tag = 'my-feature'
def my_endpoint(self, param: str = "default"):
return {"result": param}
def setup_routes(self):
self.add_route_get(self.my_endpoint)
```
2. Register in `Service__Fast_API`:
```python
def setup_routes(self):
# ... existing routes
self.add_routes(Routes__MyFeature)
```
## 🧪 Testing
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=mgraph_ai_service_cache__client
# Run specific test file
pytest tests/unit/fast_api/test_Service__Fast_API__client.py
# Run integration tests (requires LocalStack)
pytest tests/integration/
```
### Test Structure
```
tests/
├── unit/ # Unit tests
│ ├── fast_api/ # API tests
│ └── service/ # Service tests
└── deploy_aws/ # Deployment tests
```
## 🚀 Deployment
### AWS Lambda Deployment
The service includes automated deployment scripts for multiple environments:
```bash
# Deploy to development
pytest tests/deploy_aws/test_Deploy__Service__to__dev.py
# Deploy to QA
pytest tests/deploy_aws/test_Deploy__Service__to__qa.py
# Deploy to production (manual trigger)
# Use GitHub Actions workflow
```
### CI/CD Pipeline
The project uses GitHub Actions for continuous deployment:
1. **Development Branch** (`dev`)
- Runs tests with LocalStack
- Deploys to dev environment
- Increments minor version
2. **Main Branch** (`main`)
- Runs comprehensive test suite
- Deploys to QA environment
- Increments major version
3. **Production** (manual)
- Requires manual workflow trigger
- Deploys to production environment
## 🔒 Security
### Authentication
API key authentication is required for all endpoints:
```python
headers = {"x-api-key": "your-secret-key"}
```
### Best Practices
1. **Never commit secrets** - Use environment variables
2. **Rotate API keys** - Regular key rotation
3. **Use HTTPS** - Always encrypt in transit
4. **Monitor access** - Log and audit API usage
## 🤝 Contributing
We welcome contributions! Please follow these steps:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Development Guidelines
- Write tests for new features
- Update documentation
- Follow existing code style
- Add type annotations
- Consider security implications
## 🔗 Related Projects
- [OSBot-Utils](https://github.com/owasp-sbot/OSBot-Utils) - Core utilities library
- [OSBot-AWS](https://github.com/owasp-sbot/OSBot-AWS) - AWS integration layer
- [OSBot-Fast-API](https://github.com/owasp-sbot/OSBot-Fast-API) - FastAPI utilities
## 📄 License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [FastAPI](https://fastapi.tiangolo.com/)
- Deployed on [AWS Lambda](https://aws.amazon.com/lambda/)
## 📞 Support
- 🐛 Issues: [GitHub Issues](https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client/discussions)
---
Created and maintained by [The Cyber Boardroom](https://github.com/the-cyber-boardroom) team
Raw data
{
"_id": null,
"home_page": "https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client",
"name": "mgraph-ai-service-cache-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Dinis Cruz",
"author_email": "dinis.cruz@owasp.org",
"download_url": "https://files.pythonhosted.org/packages/23/c5/274b36d20ba33e54555216cf9937155bf030f9b68b0c036353647796cf14/mgraph_ai_service_cache_client-0.7.0.tar.gz",
"platform": null,
"description": "# MGraph AI Service Cache Client\n\n[](https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client/releases)\n[](https://www.python.org/downloads/)\n[](https://fastapi.tiangolo.com/)\n[](https://aws.amazon.com/lambda/)\n[](LICENSE)\n[](https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client/actions)\n\nA production-ready FastAPI microservice template for building MGraph-AI services. This template provides a complete scaffold with CI/CD pipeline, AWS Lambda deployment, and type-safe architecture.\n\n## \ud83c\udfaf Purpose\n\nThis repository serves as the base template for creating new MGraph-AI services. It includes:\n- \u2705 Complete FastAPI application structure \n- \u2705 Multi-stage CI/CD pipeline (dev, qa, prod)\n- \u2705 AWS Lambda deployment configuration\n- \u2705 Type-safe architecture using OSBot-Utils\n- \u2705 Comprehensive test coverage\n- \u2705 API key authentication\n- \u2705 Health check and monitoring endpoints\n\n**Note**: This is a template repository. To create your own service, see [Creating Services from Template](docs/dev/non-functional-requirements/version-1_0_0/README.md).\n\n## \ud83d\udcda Creating a New Service\n\nTo create a new service from this template, see [Creating Services from MGraph-AI__Service__Cache__Client](docs/dev/non-functional-requirements/version-1_0_0/README.md).\n\n## \ud83d\ude80 Features\n\n- **Type-Safe Architecture**: Built on OSBot-Utils type safety framework\n- **Multi-Stage Deployment**: Automated CI/CD pipeline for dev, QA, and production\n- **AWS Lambda Ready**: Optimized for serverless deployment\n- **API Key Authentication**: Secure access control\n\n## \ud83d\udccb Table of Contents\n\n- [Quick Start](#-quick-start)\n- [Installation](#-installation)\n- [API Documentation](#-api-documentation)\n- [Configuration](#-configuration)\n- [Development](#-development)\n- [Testing](#-testing)\n- [Deployment](#-deployment)\n- [Security](#-security)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## \ud83c\udfaf Quick Start\n\n### Local Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client.git\ncd MGraph-AI__Service__Cache__Client\n\n# Install dependencies\npip install -r requirements-test.txt\npip install -e .\n\n# Set environment variables\nexport FAST_API__AUTH__API_KEY__NAME=\"x-api-key\"\nexport FAST_API__AUTH__API_KEY__VALUE=\"your-secret-key\"\n\n# Run locally\n./scripts/run-locally.sh\n# or\nuvicorn mgraph_ai_service_cache__client.fast_api.lambda_handler:app --reload --host 0.0.0.0 --port 10011\n```\n\n### Basic Usage\n\n```python\nimport requests\n\n# Set up authentication\nheaders = {\"x-api-key\": \"your-secret-key\"}\nbase_url = \"http://localhost:10011\"\n\n# Check service health\nresponse = requests.get(f\"{base_url}/health\", headers=headers)\nprint(response.json())\n\n# Get service info\nresponse = requests.get(f\"{base_url}/info/version\", headers=headers)\nprint(response.json())\n```\n\n## \ud83d\udce6 Installation\n\n### Prerequisites\n\n- Python 3.12+\n- AWS CLI (for deployment)\n- Docker (for LocalStack testing)\n\n### Using Poetry\n\n```bash\n# Install poetry if not already installed\npip install poetry\n\n# Install dependencies\npoetry install\n\n# Activate virtual environment\npoetry shell\n```\n\n### Using pip\n\n```bash\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements-test.txt\npip install -e .\n```\n\n## \ud83d\udcd6 API Documentation\n\n### Interactive API Documentation\n\nOnce the service is running, access the interactive API documentation at:\n- Swagger UI: http://localhost:10011/docs\n- ReDoc: http://localhost:10011/redoc\n\n### Endpoints Overview\n\n#### Health Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/health` | GET | Service health check |\n| `/health/detailed` | GET | Detailed health status |\n\n#### Information Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/info/version` | GET | Get service version |\n| `/info/status` | GET | Get service status |\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n\n| Variable | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `FAST_API__AUTH__API_KEY__NAME` | Header name for API key | Yes | - |\n| `FAST_API__AUTH__API_KEY__VALUE` | API key value | Yes | - |\n| `AWS_REGION` | AWS region (triggers Lambda mode) | No | - |\n| `DEBUG` | Enable debug logging | No | false |\n\n### Configuration File\n\nCreate a `.env` file for local development:\n\n```env\nFAST_API__AUTH__API_KEY__NAME=x-api-key\nFAST_API__AUTH__API_KEY__VALUE=development-key-12345\n```\n\n## \ud83d\udee0\ufe0f Development\n\n### Project Structure\n\n```\nmgraph_ai_service_cache__client/\n\u251c\u2500\u2500 fast_api/\n\u2502 \u251c\u2500\u2500 lambda_handler.py # AWS Lambda entry point\n\u2502 \u251c\u2500\u2500 Service__Fast_API.py # FastAPI application setup\n\u2502 \u2514\u2500\u2500 routes/ # API endpoint definitions\n\u251c\u2500\u2500 service/\n\u2502 \u2514\u2500\u2500 info/ # Service information\n\u251c\u2500\u2500 utils/\n\u2502 \u251c\u2500\u2500 deploy/ # Deployment utilities\n\u2502 \u2514\u2500\u2500 Version.py # Version management\n\u2514\u2500\u2500 config.py # Service configuration\n```\n\n### Adding New Endpoints\n\n1. Create a new route class in `fast_api/routes/`:\n\n```python\nfrom osbot_fast_api.api.Fast_API_Routes import Fast_API_Routes\n\nclass Routes__MyFeature(Fast_API_Routes):\n tag = 'my-feature'\n \n def my_endpoint(self, param: str = \"default\"):\n return {\"result\": param}\n \n def setup_routes(self):\n self.add_route_get(self.my_endpoint)\n```\n\n2. Register in `Service__Fast_API`:\n\n```python\ndef setup_routes(self):\n # ... existing routes\n self.add_routes(Routes__MyFeature)\n```\n\n## \ud83e\uddea Testing\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=mgraph_ai_service_cache__client\n\n# Run specific test file\npytest tests/unit/fast_api/test_Service__Fast_API__client.py\n\n# Run integration tests (requires LocalStack)\npytest tests/integration/\n```\n\n### Test Structure\n\n```\ntests/\n\u251c\u2500\u2500 unit/ # Unit tests\n\u2502 \u251c\u2500\u2500 fast_api/ # API tests\n\u2502 \u2514\u2500\u2500 service/ # Service tests\n\u2514\u2500\u2500 deploy_aws/ # Deployment tests\n```\n\n## \ud83d\ude80 Deployment\n\n### AWS Lambda Deployment\n\nThe service includes automated deployment scripts for multiple environments:\n\n```bash\n# Deploy to development\npytest tests/deploy_aws/test_Deploy__Service__to__dev.py\n\n# Deploy to QA\npytest tests/deploy_aws/test_Deploy__Service__to__qa.py\n\n# Deploy to production (manual trigger)\n# Use GitHub Actions workflow\n```\n\n### CI/CD Pipeline\n\nThe project uses GitHub Actions for continuous deployment:\n\n1. **Development Branch** (`dev`)\n - Runs tests with LocalStack\n - Deploys to dev environment\n - Increments minor version\n\n2. **Main Branch** (`main`)\n - Runs comprehensive test suite\n - Deploys to QA environment\n - Increments major version\n\n3. **Production** (manual)\n - Requires manual workflow trigger\n - Deploys to production environment\n\n## \ud83d\udd12 Security\n\n### Authentication\n\nAPI key authentication is required for all endpoints:\n\n```python\nheaders = {\"x-api-key\": \"your-secret-key\"}\n```\n\n### Best Practices\n\n1. **Never commit secrets** - Use environment variables\n2. **Rotate API keys** - Regular key rotation\n3. **Use HTTPS** - Always encrypt in transit\n4. **Monitor access** - Log and audit API usage\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Write tests for new features\n- Update documentation\n- Follow existing code style\n- Add type annotations\n- Consider security implications\n\n## \ud83d\udd17 Related Projects\n\n- [OSBot-Utils](https://github.com/owasp-sbot/OSBot-Utils) - Core utilities library\n- [OSBot-AWS](https://github.com/owasp-sbot/OSBot-AWS) - AWS integration layer\n- [OSBot-Fast-API](https://github.com/owasp-sbot/OSBot-Fast-API) - FastAPI utilities\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [FastAPI](https://fastapi.tiangolo.com/)\n- Deployed on [AWS Lambda](https://aws.amazon.com/lambda/)\n\n## \ud83d\udcde Support\n\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client/issues)\n- \ud83d\udcac Discussions: [GitHub Discussions](https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client/discussions)\n\n---\n\nCreated and maintained by [The Cyber Boardroom](https://github.com/the-cyber-boardroom) team\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "MGraph-AI__Service__Cache__Client",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client",
"Repository": "https://github.com/the-cyber-boardroom/MGraph-AI__Service__Cache__Client"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "18143d1fe63d75da7c7d131647b96802df9fcda443e3c409692b159e1b55c3eb",
"md5": "906890eea47db956dae077216a8ac5e1",
"sha256": "63ecac8f59b2235da5cf3943161abbf2cbf74201da6cd8b198674ad53dca87e9"
},
"downloads": -1,
"filename": "mgraph_ai_service_cache_client-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "906890eea47db956dae077216a8ac5e1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 67364,
"upload_time": "2025-10-13T11:54:07",
"upload_time_iso_8601": "2025-10-13T11:54:07.064909Z",
"url": "https://files.pythonhosted.org/packages/18/14/3d1fe63d75da7c7d131647b96802df9fcda443e3c409692b159e1b55c3eb/mgraph_ai_service_cache_client-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "23c5274b36d20ba33e54555216cf9937155bf030f9b68b0c036353647796cf14",
"md5": "c8089c071f799aa0508ef619f1f550be",
"sha256": "fe827aa1eeba683a74d087b2e2b9f2f67de30607c2c30175c62d54801d2c0923"
},
"downloads": -1,
"filename": "mgraph_ai_service_cache_client-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "c8089c071f799aa0508ef619f1f550be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 31058,
"upload_time": "2025-10-13T11:54:08",
"upload_time_iso_8601": "2025-10-13T11:54:08.295400Z",
"url": "https://files.pythonhosted.org/packages/23/c5/274b36d20ba33e54555216cf9937155bf030f9b68b0c036353647796cf14/mgraph_ai_service_cache_client-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-13 11:54:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "the-cyber-boardroom",
"github_project": "MGraph-AI__Service__Cache__Client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mgraph-ai-service-cache-client"
}
JSON
