circularlink 1.0.0__tar.gz

circularlink-1.0.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: circularlink
+Version: 1.0.0
+Summary: AI-Driven Marketplace for Industrial Circular Economy — Terminal UI
+Author-email: Akshay Jha <akshay@circularlink.io>, Bandhan Sawant <bandhan@circularlink.io>, Devansh Jollani <devansh@circularlink.io>
+License: MIT
+Project-URL: Homepage, https://github.com/circularlink/circularlink
+Project-URL: Documentation, https://github.com/circularlink/circularlink#readme
+Keywords: circular-economy,AI,marketplace,TUI,Gemini,NLP
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: textual>=0.80.0
+Requires-Dist: google-generativeai>=0.8.0
+Requires-Dist: rapidfuzz>=3.9.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: geopy>=2.4.0
+
+# CircuLink Terminal
+
+> **AI-Driven Marketplace for Industrial Circular Economy**  
+> A production-quality Python TUI (Terminal User Interface) that connects industrial buyers and sellers of waste materials, by-products, and recyclables using intelligent fuzzy matching, real-time GSTIN compliance, and Gemini 2.5 Flash AI reasoning.
+
+---
+
+## Features
+
+| Feature | Detail |
+|---|---|
+| **GSTIN-gated KYC** | Full 15-character GSTIN regex validation with Indian state-code lookup |
+| **AI Byproduct Prediction** | Seller describes a process → Gemini 2.5 Flash predicts likely marketable byproducts |
+| **Hazardous Screening** | 57-substance database (CAS + name); CAS match → exact → substring → RapidFuzz ≥85 — blocked listings never appear in search |
+| **Intelligent Search** | Buyer enters a query → Gemini expands synonyms → RapidFuzz ensemble scoring → ranked results |
+| **Weighted Scoring** | `final_score = 0.7 × fuzzy_score + 0.3 × location_score` |
+| **Location Proximity** | Haversine distance + exponential decay; 100+ Indian industrial cities pre-geocoded |
+| **Persistent Storage** | `~/.circularlink/` flat-JSON store; JSONL audit trail for every LLM call |
+| **Full TUI** | Rich color scheme, sidebar navigation, modal dialogs — zero browser required |
+
+---
+
+## Quick Start
+
+```bash
+pip install circularlink
+circularlink
+```
+
+### From source (editable install)
+
+```bash
+git clone https://github.com/your-org/circularlink.git
+cd circularlink
+pip install -e .
+circularlink
+```
+
+Requires **Python 3.11+**.
+
+---
+
+## First Run
+
+1. On launch you will see the **Welcome / Login** screen.
+2. Switch to the **Register** tab.
+3. Enter your company details — GSTIN is validated live.
+4. Paste your **Google AI Studio API key** (from [aistudio.google.com](https://aistudio.google.com)).
+5. Register → you enter the main application.
+
+Subsequent launches auto-restore your session via `~/.circularlink/config.json`.
+
+> **💡 Need test data?** See [SAMPLE_DATA.md](SAMPLE_DATA.md) for ready-to-use company credentials and testing scenarios.
+
+---
+
+## Navigation
+
+| Key | Screen |
+|---|---|
+| `F1` | Dashboard — stats, recent matches, LLM audit log |
+| `F2` | Buy: Intelligent Sourcing — search / browse / history |
+| `F3` | Sell: Inventory — AI scan, manual add, hazard status |
+| `F4` | KYC / Settings — edit profile, change API key, logout |
+| `Ctrl+Q` | Quit |
+
+---
+
+## Architecture
+
+```
+src/circularlink/
+├── app.py                  # Root App — LoginEvent, LogoutEvent, screen routing
+├── __main__.py             # CLI entry point  →  circularlink
+├── styles.tcss             # Textual CSS — Industrial Earth & Tech palette
+│
+├── core/
+│   ├── gstin.py            # GSTIN regex validator + state-code lookup
+│   ├── geo.py              # City geocoding, haversine, location scoring
+│   ├── hazard.py           # 4-strategy hazardous material checker
+│   ├── matcher.py          # FuzzyMatcher: ensemble NLP + weighted geo scoring
+│   └── gemini_agent.py     # Gemini 2.5 Flash: byproduct prediction + keyword expansion
+│
+├── storage/
+│   └── db.py               # JSON persistence layer (companies, products, matches, logs)
+│
+├── screens/
+│   ├── welcome.py          # Login + Registration + live GSTIN validation
+│   ├── dashboard.py        # F1 — stats, match table, LLM log
+│   ├── buyer.py            # F2 — search, Gemini expansion, ranked results
+│   ├── seller.py           # F3 — AI byproduct scan, hazard check, inventory
+│   ├── kyc.py              # F4 — profile management, logout, account delete
+│   └── modals.py           # MessageModal, ConfirmModal, AddProductModal, SearchModal
+│
+└── data/
+    └── hazardous.csv       # 57 hazardous substances (CAS + name + UN number)
+```
+
+### Scoring Formula
+
+$$\text{final\_score} = 0.7 \times \text{fuzzy\_score} + 0.3 \times \text{location\_score}$$
+
+- **fuzzy\_score** = ensemble average of RapidFuzz `token_set_ratio`, `token_sort_ratio`, `partial_ratio` across product name and description
+- **location\_score** = $e^{-d / (R/5)}$ where $d$ is Haversine distance in km and $R$ is `max_radius_km` (default 2000 km)
+
+### Hazard Check Strategy (defence-in-depth)
+
+1. CAS number regex match against CSV
+2. Exact name match (case-insensitive)
+3. Substring containment (both directions)
+4. RapidFuzz `token_set_ratio` ≥ 85
+
+Any hit → product status set to `blocked`; never returned in buyer search.
+
+---
+
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `GOOGLE_API_KEY` | Fallback API key if none stored in DB |
+
+Recommended: set key via the **KYC / Settings** screen (stored locally, never transmitted outside Gemini API calls).
+
+---
+
+## Storage
+
+All data is stored under `~/.circularlink/`:
+
+```
+~/.circularlink/
+├── config.json         # api_key, current_company_id
+├── companies.json      # Registered companies
+├── products.json       # Product listings (approved / blocked / pending)
+├── matches.json        # Saved search results
+└── llm_logs/
+    └── YYYY-MM-DD.jsonl  # Append-only Gemini call audit log
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---|---|---|
+| `textual` | ≥0.80.0 | TUI framework |
+| `google-generativeai` | ≥0.8.0 | Gemini 2.5 Flash API |
+| `rapidfuzz` | ≥3.9.0 | Fuzzy NLP matching |
+| `rich` | ≥13.7.0 | Terminal rendering |
+| `geopy` | ≥2.4.0 | Geocoding utilities |
+
+---
+
+## Color Scheme
+
+| Role | Hex | Usage |
+|---|---|---|
+| Background Deep | `#1A1B26` | Screen background |
+| Background Panel | `#24253A` | Sidebar, cards |
+| Seller / Red | `#E06C75` | Seller UI, warnings |
+| Buyer / Green | `#98C379` | Buyer UI, success |
+| AI / Blue | `#61AFEF` | Gemini highlights |
+| Hazard / Amber | `#D19A66` | Hazard banners |
+| Accent / Purple | `#C678DD` | Hotkeys, accents |
+
+---
+
+## Publishing to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+## Acknowledgements
+
+Built with [Textual](https://github.com/Textualize/textual) by Textualize, [Google Generative AI](https://ai.google.dev/), and [RapidFuzz](https://github.com/maxbachmann/RapidFuzz).

circularlink-1.0.0/README.md

@@ -0,0 +1,187 @@
+# CircuLink Terminal
+
+> **AI-Driven Marketplace for Industrial Circular Economy**  
+> A production-quality Python TUI (Terminal User Interface) that connects industrial buyers and sellers of waste materials, by-products, and recyclables using intelligent fuzzy matching, real-time GSTIN compliance, and Gemini 2.5 Flash AI reasoning.
+
+---
+
+## Features
+
+| Feature | Detail |
+|---|---|
+| **GSTIN-gated KYC** | Full 15-character GSTIN regex validation with Indian state-code lookup |
+| **AI Byproduct Prediction** | Seller describes a process → Gemini 2.5 Flash predicts likely marketable byproducts |
+| **Hazardous Screening** | 57-substance database (CAS + name); CAS match → exact → substring → RapidFuzz ≥85 — blocked listings never appear in search |
+| **Intelligent Search** | Buyer enters a query → Gemini expands synonyms → RapidFuzz ensemble scoring → ranked results |
+| **Weighted Scoring** | `final_score = 0.7 × fuzzy_score + 0.3 × location_score` |
+| **Location Proximity** | Haversine distance + exponential decay; 100+ Indian industrial cities pre-geocoded |
+| **Persistent Storage** | `~/.circularlink/` flat-JSON store; JSONL audit trail for every LLM call |
+| **Full TUI** | Rich color scheme, sidebar navigation, modal dialogs — zero browser required |
+
+---
+
+## Quick Start
+
+```bash
+pip install circularlink
+circularlink
+```
+
+### From source (editable install)
+
+```bash
+git clone https://github.com/your-org/circularlink.git
+cd circularlink
+pip install -e .
+circularlink
+```
+
+Requires **Python 3.11+**.
+
+---
+
+## First Run
+
+1. On launch you will see the **Welcome / Login** screen.
+2. Switch to the **Register** tab.
+3. Enter your company details — GSTIN is validated live.
+4. Paste your **Google AI Studio API key** (from [aistudio.google.com](https://aistudio.google.com)).
+5. Register → you enter the main application.
+
+Subsequent launches auto-restore your session via `~/.circularlink/config.json`.
+
+> **💡 Need test data?** See [SAMPLE_DATA.md](SAMPLE_DATA.md) for ready-to-use company credentials and testing scenarios.
+
+---
+
+## Navigation
+
+| Key | Screen |
+|---|---|
+| `F1` | Dashboard — stats, recent matches, LLM audit log |
+| `F2` | Buy: Intelligent Sourcing — search / browse / history |
+| `F3` | Sell: Inventory — AI scan, manual add, hazard status |
+| `F4` | KYC / Settings — edit profile, change API key, logout |
+| `Ctrl+Q` | Quit |
+
+---
+
+## Architecture
+
+```
+src/circularlink/
+├── app.py                  # Root App — LoginEvent, LogoutEvent, screen routing
+├── __main__.py             # CLI entry point  →  circularlink
+├── styles.tcss             # Textual CSS — Industrial Earth & Tech palette
+│
+├── core/
+│   ├── gstin.py            # GSTIN regex validator + state-code lookup
+│   ├── geo.py              # City geocoding, haversine, location scoring
+│   ├── hazard.py           # 4-strategy hazardous material checker
+│   ├── matcher.py          # FuzzyMatcher: ensemble NLP + weighted geo scoring
+│   └── gemini_agent.py     # Gemini 2.5 Flash: byproduct prediction + keyword expansion
+│
+├── storage/
+│   └── db.py               # JSON persistence layer (companies, products, matches, logs)
+│
+├── screens/
+│   ├── welcome.py          # Login + Registration + live GSTIN validation
+│   ├── dashboard.py        # F1 — stats, match table, LLM log
+│   ├── buyer.py            # F2 — search, Gemini expansion, ranked results
+│   ├── seller.py           # F3 — AI byproduct scan, hazard check, inventory
+│   ├── kyc.py              # F4 — profile management, logout, account delete
+│   └── modals.py           # MessageModal, ConfirmModal, AddProductModal, SearchModal
+│
+└── data/
+    └── hazardous.csv       # 57 hazardous substances (CAS + name + UN number)
+```
+
+### Scoring Formula
+
+$$\text{final\_score} = 0.7 \times \text{fuzzy\_score} + 0.3 \times \text{location\_score}$$
+
+- **fuzzy\_score** = ensemble average of RapidFuzz `token_set_ratio`, `token_sort_ratio`, `partial_ratio` across product name and description
+- **location\_score** = $e^{-d / (R/5)}$ where $d$ is Haversine distance in km and $R$ is `max_radius_km` (default 2000 km)
+
+### Hazard Check Strategy (defence-in-depth)
+
+1. CAS number regex match against CSV
+2. Exact name match (case-insensitive)
+3. Substring containment (both directions)
+4. RapidFuzz `token_set_ratio` ≥ 85
+
+Any hit → product status set to `blocked`; never returned in buyer search.
+
+---
+
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `GOOGLE_API_KEY` | Fallback API key if none stored in DB |
+
+Recommended: set key via the **KYC / Settings** screen (stored locally, never transmitted outside Gemini API calls).
+
+---
+
+## Storage
+
+All data is stored under `~/.circularlink/`:
+
+```
+~/.circularlink/
+├── config.json         # api_key, current_company_id
+├── companies.json      # Registered companies
+├── products.json       # Product listings (approved / blocked / pending)
+├── matches.json        # Saved search results
+└── llm_logs/
+    └── YYYY-MM-DD.jsonl  # Append-only Gemini call audit log
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---|---|---|
+| `textual` | ≥0.80.0 | TUI framework |
+| `google-generativeai` | ≥0.8.0 | Gemini 2.5 Flash API |
+| `rapidfuzz` | ≥3.9.0 | Fuzzy NLP matching |
+| `rich` | ≥13.7.0 | Terminal rendering |
+| `geopy` | ≥2.4.0 | Geocoding utilities |
+
+---
+
+## Color Scheme
+
+| Role | Hex | Usage |
+|---|---|---|
+| Background Deep | `#1A1B26` | Screen background |
+| Background Panel | `#24253A` | Sidebar, cards |
+| Seller / Red | `#E06C75` | Seller UI, warnings |
+| Buyer / Green | `#98C379` | Buyer UI, success |
+| AI / Blue | `#61AFEF` | Gemini highlights |
+| Hazard / Amber | `#D19A66` | Hazard banners |
+| Accent / Purple | `#C678DD` | Hotkeys, accents |
+
+---
+
+## Publishing to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+## Acknowledgements
+
+Built with [Textual](https://github.com/Textualize/textual) by Textualize, [Google Generative AI](https://ai.google.dev/), and [RapidFuzz](https://github.com/maxbachmann/RapidFuzz).

circularlink-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "circularlink"
+version = "1.0.0"
+description = "AI-Driven Marketplace for Industrial Circular Economy — Terminal UI"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Akshay Jha", email = "akshay@circularlink.io" },
+    { name = "Bandhan Sawant", email = "bandhan@circularlink.io" },
+    { name = "Devansh Jollani", email = "devansh@circularlink.io" },
+]
+keywords = ["circular-economy", "AI", "marketplace", "TUI", "Gemini", "NLP"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Manufacturing",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "textual>=0.80.0",
+    "google-generativeai>=0.8.0",
+    "rapidfuzz>=3.9.0",
+    "rich>=13.7.0",
+    "geopy>=2.4.0",
+]
+
+[project.scripts]
+circularlink = "circularlink.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/circularlink/circularlink"
+Documentation = "https://github.com/circularlink/circularlink#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"circularlink" = ["data/*.csv", "*.tcss"]

circularlink-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

circularlink-1.0.0/src/circularlink/__init__.py

@@ -0,0 +1,13 @@
+"""
+CircuLink Terminal — AI-Driven Marketplace for Industrial Circular Economy
+==========================================================================
+Connects industrial entities to close the loop on material waste.
+
+Version: 1.0.0
+Authors: Akshay Jha, Bandhan Sawant, Devansh Jollani
+Guide: Prof. Samiran Maity
+Institution: Dwarkadas J. Sanghvi College of Engineering, University of Mumbai
+"""
+
+__version__ = "1.0.0"
+__app_name__ = "CircuLink Terminal"

circularlink-1.0.0/src/circularlink/__main__.py

@@ -0,0 +1,24 @@
+"""Entry point — invoked via `circularlink` CLI command."""
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    """Launch the CircuLink Terminal application."""
+    # Guard: Python 3.11+ required for match-statements and TaskGroup
+    if sys.version_info < (3, 11):
+        print(
+            "CircuLink requires Python 3.11 or later.\n"
+            f"You are running Python {sys.version}."
+        )
+        sys.exit(1)
+
+    from circularlink.app import CircuLinkApp
+
+    app = CircuLinkApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()