fix(deploy): improve deploy script and readme (#91)

Author: dineshpinto

.dockerignore

@@ -17,6 +17,7 @@ wheels/
 *.egg-info
 
 # Other folders
+.github
 docs/
 examples/
 tests/

.env.example

@@ -22,7 +22,7 @@ GCP__MACHINE_TYPE=c3-standard-4
 GCP__SERVICE_ACCOUNT=confidential-sa@verifiable-ai-hackathon.iam.gserviceaccount.com 
 GCP__TEE_IMAGE_REFERENCE=ghcr.io/flare-foundation/flare-ai-kit:main
 # For production, use `confidential-space-250301`
-GCP__IMAGE=confidential-space-debug-250301
+GCP__CONFIDENTIAL_IMAGE=confidential-space-debug-250301
 # For production, use `false`
 GCP__TEE_CONTAINER_LOG_REDIRECT=true
 GCP__CONFIDENTIAL_COMPUTE_TYPE=TDX

CONTRIBUTING.md

@@ -6,8 +6,13 @@ We welcome contributions from the community to help make this SDK robust, featur
 
 ## How to Contribute
 
-- **Pull Requests (PRs)** for bug fixes, features, and documentation updates.
-- **Bug Reports** for issues you encounter.
+1. Search existing issues/PRs to avoid duplicates.
+2. For opening an issue, use labels `bug`, `feature`, `docs`, or `question`.
+3. Fork the repo and create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+4. Implement, test, then submit a PR referencing the issue.
 
 ## ✨ Write High-Quality Code
 
@@ -19,12 +24,17 @@ We strive for high-quality, maintainable code. Please adhere to the following pr
     - Design clear, minimal, and predictable interfaces for functions and classes.
     - Use descriptive names for variables, functions, and classes.
     - Keep code focused and avoid unnecessary complexity.
+    - Use [Google-style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) docstrings.
 
-2.  **Formatting, Linting & Type-Checking:**
+2.  **Use dependencies sparingly:**
+
+    - Every dependency added is a potential security risk.
+    - If the dependency is required, it should live in under `[project.optional-dependencies]` with a key marking the high level function, e.g. `rag`, `consensus`.
+
+3.  **Formatting, Linting & Type-Checking:**
 
     - Use [ruff](https://docs.astral.sh/ruff/) for formatting and linting, both settings are defined in `pyproject.toml`.
-    - Use [pyright](https://github.com/microsoft/pyright) for type checking, all new code MUST include accurate type hints.
-    - Avoid using `typing.Any` unless absolutely necessary and clearly justified in comments.
+    - Use [pyright](https://github.com/microsoft/pyright) for type checking, all new code MUST include accurate type hints. Avoid using `typing.Any` unless absolutely necessary and clearly justified in comments.
     - You can also install [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) into VSCode for an easier experience.
     - Ensure your code passes all checks locally without errors:
       ```bash
@@ -33,37 +43,37 @@ We strive for high-quality, maintainable code. Please adhere to the following pr
       uv run pyright
       ```
 
-3.  **Use dependencies sparingly:**
-    - Every dependency added is a potential security risk.
-    - If the dependency is required, it should live in under `[project.optional-dependencies]` with a key marking the high level function, e.g. `rag`, `consensus`.
-
-## 🧪 Test Extensively
+4.  **Test Extensively:**
 
-- New features **must** include appropriate unit and/or integration tests using `pytest`.
-- Bug fixes **should** include tests demonstrating the fix.
-- **All tests must pass** locally before submitting a pull request. Run tests via:
+    - New features **must** include appropriate unit and/or integration tests using `pytest`.
+    - Bug fixes **should** include tests demonstrating the fix.
+    - **All tests must pass** locally before submitting a pull request. Run tests via:
+      ```bash
+      uv run pytest tests/unit/your-test.py -v
+      uv run pytest tests/integration/your-test.py -v
+      ```
 
-  ```bash
-  # Run all tests (unit + integration, requires env vars for integration)
-  uv run pytest
-  ```
+5.  **Use Conventional Commits:**
 
-## 🚨 CI Checks Must Pass
+    - All commit messages **must** adhere to the **Conventional Commits** specification. This helps automate changelog generation and provides a clear commit history.
+    - Read the spec: [https://www.conventionalcommits.org/](https://www.conventionalcommits.org/)
+    - **Format:** `<type>[optional scope]: <description>`
+    - **Examples:**
+      - `feat(rag): add support for Neo4j AuraDB connection`
+      - `fix(ecosystem): correct decimal calculation in FTSO price feed`
+      - `docs(readme): update README with installation instructions`
+      - `test(rag): add unit tests for GraphDbSettingsModel`
+      - `chore(deps): update ruff version in pyproject.toml`
 
-- We use Continuous Integration (CI) pipelines (e.g., GitHub Actions) to automatically run linters, type checkers, and tests.
-- **Pull requests will only be considered for merging if all CI checks pass.** Ensure your code meets all quality gates before submitting.
+## 🚨 PR Checklist
 
-## ✅ Use Conventional Commits
+Before you mark your PR as ready-to-review:
 
-- All commit messages **MUST** adhere to the **Conventional Commits** specification. This helps automate changelog generation and provides a clear commit history.
-- Please read the specification: [https://www.conventionalcommits.org/](https://www.conventionalcommits.org/)
-- **Format:** `<type>[optional scope]: <description>`
-- **Examples:**
-  - `feat(rag): add support for Neo4j AuraDB connection`
-  - `fix(ecosystem): correct decimal calculation in FTSO price feed`
-  - `docs(readme): update README with installation instructions`
-  - `test(rag): add unit tests for GraphDbSettingsModel`
-  - `chore(deps): update ruff version in pyproject.toml`
+- [ ] Branch is up-to-date with `main`.
+- [ ] All linting, formatting, and type checks pass.
+- [ ] Tests cover new code (unit + integration).
+- [ ] Commit messages follow Conventional Commits.
+- [ ] PR description includes purpose and implementation details.
 
 ## 📜 License
 

README.md

@@ -22,41 +22,64 @@ SDK for building **verifiable AI Agents** on Flare using Confidential Space.
 The kit is composed of modular engines for agents, social feeds, onchain data, and consensus.
 
 ```mermaid
-graph TD
-    A(Flare AI Kit)
-    A --> B{Agent Framework - PydanticAI}
-    A --> C{VectorRAG Engine - PostgreSQL + pgvector}
-    A --> D{GraphRAG Engine - Neo4j}
-    A --> E{Secure Enclave - Confidential Space + TDX}
-    A --> F{Ecosystem Engine}
-    A --> G{Social Engine}
-    A --> H{Consensus Engine}
-
-    B --> I(Gemini, GPT, Grok +200 models)
-
-    C --o DevHub/News/Governance
-
-    D --o MainnetTxData
-
-    E --> vTPM
-    vTPM --o RA-TLS
-
-    F --o M(Protocols)
-    M --o FTSO
-    M --o FDC
-    M --o FAssets
-
-    F --o L(Applications)
-    L --o OpenOcean
-    L --o Kinetic
-    L --o SparkDEX
-    L --o Cyclo
-    L --o ...
+flowchart TD
+    A["Flare AI Kit"]
+
+    %% Agent Framework subgraph
+    subgraph AgentFramework["Agent Framework"]
+        B["Google ADK"]
+        B --o LLM["Gemini<br>GPT<br>Grok<br>+200 models"]
+    end
+
+    %% VectorRAG Engine subgraph
+    subgraph VectorRAG["VectorRAG Engine"]
+        C["Qdrant"]
+        C --o SOURCE[DevHub<br>Flare News<br>Flare Governance]
+    end
+
+    %% Secure Enclave subgraph
+    subgraph SecureEnclave["Secure Enclave"]
+        E["Confidential Space"]
+        E --> HW[Intel TDX]
+        HW --o RA[RA-verify<br>RA-TLS]
+    end
+
+    %% Ecosystem Engine subgraph
+    subgraph EcosystemEngine["Ecosystem Engine"]
+        F[Ecosystem Engine]
+        F --> PR[Protocols]
+        PR --o PROTOS["FTSO<br>FDC<br>FAssets"]
+        F --> AP[Applications]
+        AP --o APPS[SparkDEX<br>OpenOcean<br>Kinetic<br>Cyclo]
+    end
+
+    %% Social Engine subgraph
+    subgraph SocialEngine["Social Engine"]
+        G["Social"]
+        G --o SOC["X<br>Telegram<br>Farcaster<br>Slack"]
+    end
+
+    %% Consensus Engine subgraph
+    subgraph ConsensusEngine["Consensus Engine"]
+        H["Consensus"]
+        H --o ALGOS[Majority<br>Tournament<br>Clustering]
+    end
+
+    %% Connections to Flare AI Kit central node
+    A --> B
+    A --> C
+    A --> E
+    A --> F
+    A --> G
+    A --> H
 ```
 
 ## 📦 Getting Started
 
-**Prerequisites** Python >= 3.12 and [uv](https://github.com/astral-sh/uv).
+**Prerequisites**
+
+- [uv](https://github.com/astral-sh/uv) with Python >= 3.12
+- [Docker](https://www.docker.com).
 
 1. **Clone the repo:**
 
@@ -94,6 +117,13 @@ uv run pyright
 uv run pytest
 ```
 
+## 🚧 Build with Docker
+
+```bash
+docker build -t flare-ai-kit .
+docker run -rm --env-file .env flare-ai-kit
+```
+
 ## ☁️ Deploy to Confidential Space
 
 **Prerequisites:** Authenticated [gcloud CLI](https://cloud.google.com/sdk/docs/install).

gcloud-deploy.sh

@@ -26,7 +26,7 @@ fi
 : "${GCP__MACHINE_TYPE:?Please set GCP__MACHINE_TYPE}"
 : "${GCP__TEE_IMAGE_REFERENCE:?Please set GCP__TEE_IMAGE_REFERENCE}"
 : "${GCP__SERVICE_ACCOUNT:?Please set GCP__SERVICE_ACCOUNT}"
-: "${GCP__IMAGE:?Please set GCP__IMAGE}"
+: "${GCP__CONFIDENTIAL_IMAGE:?Please set GCP__CONFIDENTIAL_IMAGE}"
 : "${GCP__CONFIDENTIAL_COMPUTE_TYPE:?Please set GCP__CONFIDENTIAL_COMPUTE_TYPE}"
 : "${GCP__SCOPES:?Please set GCP__SCOPES}"
 : "${GCP__TAGS:?Please set GCP__TAGS}"
@@ -36,7 +36,7 @@ echo "--> Creating instance '$GCP__INSTANCE_NAME' in project '$GCP__PROJECT' wit
 echo "      - Zone: $GCP__ZONE"
 echo "      - Machine Type: $GCP__MACHINE_TYPE"
 echo "      - Service Account: $GCP__SERVICE_ACCOUNT"
-echo "      - Image: $GCP__IMAGE"
+echo "      - Image: $GCP__CONFIDENTIAL_IMAGE"
 echo "      - TEE Image Reference: $GCP__TEE_IMAGE_REFERENCE"
 echo "      - Confidential Compute Type: $GCP__CONFIDENTIAL_COMPUTE_TYPE"
 echo "      - Scopes: $GCP__SCOPES"
@@ -77,7 +77,7 @@ COMMAND=(
   --service-account="$GCP__SERVICE_ACCOUNT"
   --scopes="$GCP__SCOPES"
   --tags="$GCP__TAGS"
-  --create-disk=auto-delete=yes,boot=yes,device-name="$GCP__INSTANCE_NAME",image=projects/confidential-space-images/global/images/"$GCP__IMAGE",mode=rw,size=11,type=pd-balanced
+  --create-disk=auto-delete=yes,boot=yes,device-name="$GCP__INSTANCE_NAME",image=projects/confidential-space-images/global/images/"$GCP__CONFIDENTIAL_IMAGE",mode=rw,size=11,type=pd-balanced
   --shielded-secure-boot
   --shielded-vtpm
   --shielded-integrity-monitoring