Merge pull request #31 from goldlabelapps/staging

This pull request introduces new endpoints for reading prospect data and improves the documentation for the FastAPI/Postgres application.

Author: goldlabelapps

README.md

@@ -1,6 +1,6 @@
-## I
+## I_Python
 
-> FastAPI/Python/Postgres/tsvector. 
+> Python with FastAPI using Postgres & tsvector. 
 Open Source, production ready Python FastAPI/Postgres app for [NX](https://goldlabel.pro?s=python-nx-ai)
 
 ```sh
@@ -32,7 +32,8 @@ The API is at <http://localhost:8000>.
 The prospects table includes a `search_vector` column (type: tsvector) that is automatically computed from all text fields on insert. A GIN index is created for this column, enabling fast and scalable full-text search queries.
 
 **How it works:**
-- On every insert (via `/prospects/seed` or `/prospects/process`), the `search_vector` is computed from all text columns using PostgreSQL's `to_tsvector('english', ...)`.
+
+- On every insert or update, the `search_vector` is computed from all text columns using PostgreSQL's `to_tsvector('english', ...)`.
 - The GIN index (`idx_prospects_search_vector`) allows efficient search queries like:
 
 ```sql
@@ -45,52 +46,13 @@ This makes searching across all text fields in the prospects table extremely fas
 - **Pytest** — testing framework
 - **HTTPX / TestClient**
 
+#### Docs
+
 FastAPI automatically generates interactive documentation:
 
 - Swagger UI: <http://localhost:8000/docs>
 - ReDoc: <http://localhost:8000/redoc>
 
-#### Structure
-
-```
-app/
-  __init__.py
-  main.py          # FastAPI application entry point
-  api/
-    __init__.py
-    routes.py      # API endpoint definitions
-tests/
-  __init__.py
-  test_routes.py   # Unit and integration tests
-requirements.txt
-```
-
-
-#### Endpoints
-
-| Method | Path      | Description                     |
-|--------|-----------|---------------------------------|
-| GET    | `/`       | Welcome message                 |
-| GET    | `/health` | Health check — returns `ok`     |
-| POST   | `/echo`   | Echoes the JSON `message` field |
-| GET    | `/prospects/seed` | (Re)create prospects table and seed with sample data |
-| DELETE | `/prospects/process` | (Legacy) Empties the prospects table |
-| GET    | `/prospects/process` | Process and insert all records from big.csv into prospects table |
-
 ### Processing Large CSV Files
 
 The `/prospects/process` endpoint is designed for robust, scalable ingestion of large CSV files (e.g., 1300+ rows, 300KB+). It follows the same normalization and insertion pattern as `/prospects/seed`, but is optimized for large files:
-
-
-#### Example usage
-
-1. Seed the table structure:
-  - `GET /prospects/seed`
-2. (Optional) Empty the table:
-  - `DELETE /prospects/empty`
-3. Process the large CSV:
-  - `GET /prospects/process`
-
-The endpoint will return the number of records inserted. This is the core ingestion workflow for production-scale data.
-
-

app/api/prospects/prospects.py

@@ -1,20 +1,66 @@
+
 from app import __version__
 import os
 from app.utils.make_meta import make_meta
-from fastapi import APIRouter
+from fastapi import APIRouter, Query, Path
 from app.utils.db import get_db_connection
 
 router = APIRouter()
-    
 base_url = os.getenv("BASE_URL", "http://localhost:8000")
 
 @router.get("/prospects")
 def root() -> dict:
     """GET /prospects endpoint."""
-    meta = make_meta("success", "Prospects placeholder")
-    data = {"init": f"{base_url}/prospects/init"}
+    meta = make_meta("success", "Prospects start")
+    data = [
+        {"init": f"{base_url}/prospects/init"},
+        {"single": f"{base_url}/prospects/101"},
+        {"read": f"{base_url}/prospects/read"},
+    ]
     return {"meta": meta, "data": data}
 
+
+# endpoint: /prospects/read
+@router.get("/prospects/read")
+def prospects_read(
+    page: int = Query(1, ge=1, description="Page number (1-based)"),
+    limit: int = Query(50, ge=1, le=500, description="Records per page (default 50, max 500)")
+) -> dict:
+    """Read and return paginated rows from the prospects table."""
+    meta = make_meta("success", "Read paginated prospects")
+    conn_gen = get_db_connection()
+    conn = next(conn_gen)
+    cur = conn.cursor()
+    offset = (page - 1) * limit
+    try:
+        cur.execute('SELECT COUNT(*) FROM prospects;')
+        count_row = cur.fetchone() if cur.description is not None else None
+        total = count_row[0] if count_row is not None else 0
+        cur.execute(f'SELECT * FROM prospects OFFSET %s LIMIT %s;', (offset, limit))
+        if cur.description is not None:
+            columns = [desc[0] for desc in cur.description]
+            rows = cur.fetchall()
+            data = [dict(zip(columns, row)) for row in rows]
+        else:
+            data = []
+    except Exception as e:
+        data = []
+        total = 0
+        meta = make_meta("error", f"Failed to read prospects: {str(e)}")
+    finally:
+        cur.close()
+        conn.close()
+    return {
+        "meta": meta,
+        "pagination": {
+            "page": page,
+            "limit": limit,
+            "total": total,
+            "pages": (total // limit) + (1 if total % limit else 0)
+        },
+        "data": data,
+    }
+
 # endpoint: /prospects/init
 @router.get("/prospects/init")
 def prospects_init() -> dict:
@@ -98,3 +144,33 @@ def slugify(text):
         },
     }
     return {"meta": meta, "data": data}
+
+
+# endpoint: /prospects/{id}
+@router.get("/prospects/{id}")
+def prospects_read_one(id: int = Path(..., description="ID of the prospect to retrieve")) -> dict:
+    """Read and return a single prospect document by id."""
+    meta = make_meta("success", f"Read prospect with id {id}")
+    conn_gen = get_db_connection()
+    conn = next(conn_gen)
+    cur = conn.cursor()
+    try:
+        cur.execute('SELECT * FROM prospects WHERE id = %s;', (id,))
+        if cur.description is not None:
+            row = cur.fetchone()
+            if row is not None:
+                columns = [desc[0] for desc in cur.description]
+                data = dict(zip(columns, row))
+            else:
+                data = None
+                meta = make_meta("error", f"No prospect found with id {id}")
+        else:
+            data = None
+            meta = make_meta("error", f"No prospect found with id {id}")
+    except Exception as e:
+        data = None
+        meta = make_meta("error", f"Failed to read prospect: {str(e)}")
+    finally:
+        cur.close()
+        conn.close()
+    return {"meta": meta, "data": data}

app/utils/make_meta.py

@@ -10,6 +10,6 @@ def make_meta(severity: str, title: str) -> dict:
         "severity": severity,
         "title": title,
         "version": __version__,
-        "base_url": base_url,
+        "endpoint": f"{base_url}/prospects",
         "time": epoch,
     }