Feature/sam 260013: Publishing package PYPi

Makefile

@@ -0,0 +1,31 @@
+.PHONY: install lint format type test run api clean
+
+PORT ?= 8501
+install:
+	poetry install
+
+lint:
+	poetry run ruff check .
+	poetry run black --check .
+	poetry run mypy .
+
+hooks:
+	poetry run scripts/setup-hooks.sh
+
+format:
+	poetry run black .
+	poetry run ruff check --fix .
+
+type:
+	poetry run mypy .
+
+
+dev:
+	poetry run sample dev --port $(PORT)
+
+api:
+	poetry run sample api
+
+clean:
+	find . -type d -name "__pycache__" -exec rm -rf {} +
+	rm -rf .pytest_cache .mypy_cache dist build

README.md

@@ -45,7 +45,7 @@ poetry install  --all-extras --with dev
 Or manually
 
 ```bash
-poetry install
+make install
 ```
 
 ## How to Run
@@ -64,17 +64,20 @@ setup `.env.development` and `.env.production` in project root
 ## Run Streamlit App
 
 ```bash
+make dev
+#or
 poetry run sample dev
+
 ```
 
 Access: <http://localhost:8501>
 
 ## Run FastAPI Server
 
 ```bash
+make api
+#OR
 poetry run sample api
-# OR
-python src/api/fast_api.py
 ```
 
 Access: <http://127.0.0.1:5000>
@@ -84,7 +87,7 @@ Access: <http://127.0.0.1:5000>
 Pre-commit hooks are enabled. If commits fail, run:
 
 ```bash
-poetry run lint
+make lint
 ```
 
 or run individual
@@ -101,6 +104,7 @@ poetry run ruff check .
 ## Build Package
 
 ```bash
+
 poetry clean
 poetry build
 ```
@@ -146,7 +150,7 @@ these hooks will
 
 ```bash
 # Install git hooks
-poetry run ./scripts/setup-hooks.sh
+make hooks
 ```
 
 there is `.vscode/Python.code-profile` file; import this as a profile in vscode which include necessary extension for python development.

src/sample/__main__.py

@@ -8,37 +8,33 @@
 from . import __version__
 
 
-def main():
+def main(port: int = 8501):
     """
     Entrypoint for the Streamlit 'dev' app.
     """
     print("🏷️ Sample version:", __version__)
     logging.info("Starting sample dev script...")
 
-    # Paths
     Sample_dir = Path(__file__).resolve().parent
-    dev_root = Sample_dir.parent  # src/
-    wheel_root = Sample_dir.parent  # same in wheel
+    dev_root = Sample_dir.parent
+    wheel_root = Sample_dir.parent
 
-    # Add correct root to sys.path
-    if "site-packages" in str(Sample_dir):  # running from wheel
+    if "site-packages" in str(Sample_dir):
         if str(wheel_root) not in sys.path:
             sys.path.append(str(wheel_root))
             logging.info(f"Added wheel root to sys.path: {wheel_root}")
-    else:  # dev mode
+    else:
         if str(dev_root) not in sys.path:
             sys.path.append(str(dev_root))
             logging.info(f"Added dev src root to sys.path: {dev_root}")
 
-    # Locate streamlit_app.py
     streamlit_app_path = Sample_dir / "streamlit_app.py"
     logging.info(f"Streamlit app path: {streamlit_app_path}")
 
     if not streamlit_app_path.exists():
         logging.error(f"Streamlit app not found at: {streamlit_app_path}")
         return
 
-    # Run Streamlit app
     python_path = sys.executable
     logging.info(f"Using Python executable: {python_path}")
 
@@ -50,11 +46,11 @@ def main():
             "run",
             str(streamlit_app_path.resolve()),
             "--server.port",
-            "8501",
+            str(port),
         ],
         check=True,
     )
 
 
 if __name__ == "__main__":
-    main()
+    main(port=8501)

src/sample/cli.py

@@ -22,10 +22,13 @@ def cli(ctx, version):
 
 
 @cli.command(help="Run the Sample Streamlit app.")
-def dev():
+@click.option(
+    "--port", default=8501, show_default=True, help="Port to run the Streamlit app on."
+)
+def dev(port: int):
     from sample.__main__ import main
 
-    main()
+    main(port)
 
 
 @cli.command(help="Run the Sample FastAPI backend.")

templates/faq.html

@@ -30,4 +30,109 @@ <h1>Frequently Asked Questions</h1>
     <p>This is a useful to start the development with pre-defined template and best practices and define folder
       structure.</p>
   </details>
-</div>
+</div>
+<div id="technical-faq" class="faq-container">
+  <h1>Technical FAQ</h1>
+
+  <details>
+    <summary>Which Python version is supported?</summary>
+    <p>
+      Python ≥ 3.11 is required. Verify using:
+    </p>
+    <pre><code>python --version</code></pre>
+  </details>
+
+  <details>
+    <summary>How do I install dependencies?</summary>
+    <p>
+      Use the Makefile command:
+    </p>
+    <pre><code>make install</code></pre>
+    <p>
+      This runs <code>poetry install</code> internally.
+    </p>
+  </details>
+
+  <details>
+    <summary>How do I run the Streamlit app?</summary>
+    <pre><code>make dev</code></pre>
+    <p>
+      This executes <code>poetry run sample dev</code>.
+    </p>
+  </details>
+
+  <details>
+    <summary>How do I run the FastAPI server?</summary>
+    <pre><code>make api</code></pre>
+    <p>
+      This executes <code>poetry run sample api</code>.
+    </p>
+  </details>
+
+  <details>
+    <summary>How do I run linting and type checks?</summary>
+    <pre><code>make lint</code></pre>
+    <p>
+      This runs ruff, black (check mode), and mypy.
+    </p>
+  </details>
+
+  <details>
+    <summary>How do I auto-format the code?</summary>
+    <pre><code>make format</code></pre>
+    <p>
+      This runs black and ruff with auto-fix enabled.
+    </p>
+  </details>
+
+
+  <details>
+    <summary>How do I clean cache and build artifacts?</summary>
+    <pre><code>make clean</code></pre>
+    <p>
+      This removes __pycache__, mypy cache, pytest cache, and build artifacts.
+    </p>
+  </details>
+
+  <details>
+    <summary>Where is the virtual environment created?</summary>
+    <p>
+      Poetry manages the virtual environment automatically.
+      To inspect:
+    </p>
+    <pre><code>poetry env info</code></pre>
+  </details>
+
+  <details>
+    <summary>When should I regenerate poetry.lock?</summary>
+    <p>
+      Only when adding or upgrading dependencies.
+    </p>
+    <pre><code>poetry lock --no-cache --regenerate</code></pre>
+    <p>
+      Avoid unnecessary lock file changes in pull requests.
+    </p>
+  </details>
+
+  <details>
+    <summary>What if pymongo is not found?</summary>
+    <p>
+      MongoDB support is an optional extra dependency.
+      Install using:
+    </p>
+    <pre><code>pip install sample[mongo]</code></pre>
+    <p>
+      If using Poetry:
+    </p>
+    <pre><code>poetry install --extras "mongo"</code></pre>
+  </details>
+
+  <details>
+    <summary>Are secrets allowed inside the repository?</summary>
+    <p>
+      No. Never commit secrets. Use environment variables or external secret managers.
+      Maintain a <code>.env.example</code> file for documentation purposes.
+    </p>
+  </details>
+
+</div>