equitable-capital-optimization-ai 0.2.0__tar.gz

equitable_capital_optimization_ai-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sakera Begum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

equitable_capital_optimization_ai-0.2.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: equitable-capital-optimization-ai
+Version: 0.2.0
+Summary: Research package for predictive capital-readiness analysis, fairness auditing, explainable AI, and equity-aware capital allocation.
+Author: Sakera Begum
+License: MIT
+Project-URL: Homepage, https://github.com/sakera023/equitable-capital-optimization-ai
+Project-URL: Repository, https://github.com/sakera023/equitable-capital-optimization-ai
+Project-URL: Issues, https://github.com/sakera023/equitable-capital-optimization-ai/issues
+Project-URL: Documentation, https://github.com/sakera023/equitable-capital-optimization-ai/tree/main/docs
+Project-URL: Publication, https://www.researchgate.net/publication/410866072_An_AI-Powered_Framework_for_Equitable_Capital_Optimization_Leveraging_Predictive_Intelligence_to_Empower_Underserved_Entrepreneurial_Ecosystems_in_the_US
+Keywords: artificial-intelligence,machine-learning,predictive-analytics,entrepreneurship,small-business,capital-allocation,fairness,responsible-ai,explainable-ai,streamlit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pandas<4,>=2.1
+Requires-Dist: plotly<8,>=5.20
+Requires-Dist: scikit-learn<2,>=1.4
+Requires-Dist: streamlit<2,>=1.40
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.8; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+Dynamic: license-file
+
+# Equitable Capital Optimization AI
+
+[![CI](https://github.com/sakera023/equitable-capital-optimization-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/sakera023/equitable-capital-optimization-ai/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
+![Streamlit](https://img.shields.io/badge/Streamlit-App-FF4B4B?logo=streamlit&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+A reproducible research prototype for **predictive capital-readiness analysis, model
+explainability, fairness auditing, and equity-aware capital-allocation simulation** for
+underserved U.S. entrepreneurial ecosystems.
+
+The project is inspired by:
+
+> **An AI-Powered Framework for Equitable Capital Optimization: Leveraging Predictive
+> Intelligence to Empower Underserved Entrepreneurial Ecosystems in the U.S.**
+
+Related publication:
+[ResearchGate](https://www.researchgate.net/publication/410866072_An_AI-Powered_Framework_for_Equitable_Capital_Optimization_Leveraging_Predictive_Intelligence_to_Empower_Underserved_Entrepreneurial_Ecosystems_in_the_US)
+
+## Why this project exists
+
+Access to capital is not only a prediction problem. It is also an allocation,
+transparency, and measurement problem. This repository separates those concerns into
+four independently testable components:
+
+| Component | Purpose |
+| --- | --- |
+| Predictive modeling | Estimate funding-success probability from business and market features |
+| Explainability | Show how applicant-level features influence the model locally |
+| Fairness auditing | Compare outcomes across structural-access contexts |
+| Capital allocation | Compare efficiency-only and equity-aware funding scenarios |
+
+## Responsible-use boundary
+
+> **Research and educational use only.**
+>
+> This project must not be used to make real lending, credit, investment, employment,
+> housing, insurance, benefits, or eligibility decisions.
+
+The predictive model intentionally excludes protected personal characteristics.
+Structural context indicators are used for research auditing and allocation simulation,
+not as protected-trait proxies for real-world underwriting.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A[Synthetic Business Data] --> B[Feature Pipeline]
+    B --> C[Random Forest Model]
+    C --> D[Capital Readiness Score]
+    C --> E[Local Explanation]
+    D --> F[Fairness Audit]
+    D --> G[Allocation Simulator]
+    F --> H[Research Dashboard]
+    G --> H
+    E --> H
+```
+
+See [Architecture](docs/ARCHITECTURE.md) and [Methodology](docs/METHODOLOGY.md).
+
+## Key capabilities
+
+- Reproducible synthetic U.S. small-business/startup data generation
+- Scikit-learn preprocessing and Random Forest classification pipeline
+- Holdout evaluation with ROC-AUC, accuracy, precision, recall, F1, and Brier score
+- Capital Readiness Score derived from predicted funding-success probability
+- Global feature-importance reporting
+- Applicant-level local sensitivity explanations
+- Structural-context fairness audit and selection-rate comparison
+- Efficiency-only and equity-aware capital-allocation simulation
+- Interactive Streamlit research dashboard
+- Automated tests and linting in GitHub Actions
+- Model card, citation metadata, contribution guide, and security policy
+
+## Python package
+
+The reusable research code lives in the `equitable_capital` Python package.
+
+After a release is published to PyPI, install it with:
+
+```bash
+pip install equitable-capital-optimization-ai
+```
+
+Example:
+
+```python
+from equitable_capital import (
+    allocate_capital,
+    fairness_audit,
+    generate_synthetic_startups,
+    train_model,
+)
+
+data = generate_synthetic_startups()
+result = train_model(data)
+audit = fairness_audit(result.scored_data)
+```
+
+For local development, install the repository in editable mode:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```bash
+git clone https://github.com/sakera023/equitable-capital-optimization-ai.git
+cd equitable-capital-optimization-ai
+python -m venv .venv
+```
+
+Activate the environment.
+
+**Windows**
+
+```bash
+.venv\Scripts\activate
+```
+
+**macOS/Linux**
+
+```bash
+source .venv/bin/activate
+```
+
+Install and run:
+
+```bash
+pip install -r requirements.txt
+streamlit run app.py
+```
+
+Development checks:
+
+```bash
+pip install -r requirements-dev.txt
+ruff check src tests app.py
+python -m pytest -q
+```
+
+## Repository structure
+
+```text
+.
+├── app.py
+├── pyproject.toml
+├── requirements.txt
+├── requirements-dev.txt
+├── Makefile
+├── src/
+│   └── equitable_capital/
+│       ├── __init__.py
+│       ├── allocation.py
+│       ├── config.py
+│       ├── data.py
+│       ├── explainability.py
+│       ├── fairness.py
+│       └── modeling.py
+├── tests/
+├── docs/
+├── .github/
+├── CITATION.cff
+├── CONTRIBUTING.md
+├── SECURITY.md
+├── CHANGELOG.md
+└── LICENSE
+```
+
+## Data design
+
+The repository uses **synthetic data by default**. This avoids exposing private
+financial records, makes the project reproducible, and prevents the demonstration from
+implying real-world predictive validity.
+
+Predictive features include revenue, growth, cash runway, employees, operating history,
+debt-service coverage, digital adoption, market demand, management capacity, requested
+capital, industry, and state.
+
+## Model evaluation
+
+The application reports ROC-AUC, accuracy, precision, recall, F1 score, and Brier score.
+These metrics evaluate the synthetic demonstration only.
+
+## Fairness and equity analysis
+
+A **structural barrier index** is built from contextual variables such as low-income
+area, rural area, limited finance access, and digital adoption.
+
+The index is reserved for post-model fairness diagnostics and research simulation of
+equity-aware allocation policies. It is not included in the predictive training
+features.
+
+## Reproducibility
+
+The synthetic data generator and model pipeline use explicit random seeds. Tests verify
+data ranges, prediction bounds, allocation-budget constraints, and fairness-audit
+outputs. CI runs on every push and pull request.
+
+## Research roadmap
+
+Planned extensions include gradient-boosted model benchmarks, probability calibration,
+SHAP, temporal/geographic validation, county-level opportunity maps, Census/SBA/CDFI
+public-data integrations, constrained optimization, and uncertainty analysis.
+
+See [Research Roadmap](docs/RESEARCH_ROADMAP.md).
+
+## Citation
+
+If you use the software, cite the repository metadata in [CITATION.cff](CITATION.cff).
+If you use the associated research concept, cite the publication separately and clearly
+distinguish research findings from this software prototype.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+Do not publish secrets, private financial information, or real applicant records in
+issues or pull requests. See [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Maintainer
+
+**Sakera Begum**

equitable_capital_optimization_ai-0.2.0/README.md

@@ -0,0 +1,230 @@
+# Equitable Capital Optimization AI
+
+[![CI](https://github.com/sakera023/equitable-capital-optimization-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/sakera023/equitable-capital-optimization-ai/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
+![Streamlit](https://img.shields.io/badge/Streamlit-App-FF4B4B?logo=streamlit&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+A reproducible research prototype for **predictive capital-readiness analysis, model
+explainability, fairness auditing, and equity-aware capital-allocation simulation** for
+underserved U.S. entrepreneurial ecosystems.
+
+The project is inspired by:
+
+> **An AI-Powered Framework for Equitable Capital Optimization: Leveraging Predictive
+> Intelligence to Empower Underserved Entrepreneurial Ecosystems in the U.S.**
+
+Related publication:
+[ResearchGate](https://www.researchgate.net/publication/410866072_An_AI-Powered_Framework_for_Equitable_Capital_Optimization_Leveraging_Predictive_Intelligence_to_Empower_Underserved_Entrepreneurial_Ecosystems_in_the_US)
+
+## Why this project exists
+
+Access to capital is not only a prediction problem. It is also an allocation,
+transparency, and measurement problem. This repository separates those concerns into
+four independently testable components:
+
+| Component | Purpose |
+| --- | --- |
+| Predictive modeling | Estimate funding-success probability from business and market features |
+| Explainability | Show how applicant-level features influence the model locally |
+| Fairness auditing | Compare outcomes across structural-access contexts |
+| Capital allocation | Compare efficiency-only and equity-aware funding scenarios |
+
+## Responsible-use boundary
+
+> **Research and educational use only.**
+>
+> This project must not be used to make real lending, credit, investment, employment,
+> housing, insurance, benefits, or eligibility decisions.
+
+The predictive model intentionally excludes protected personal characteristics.
+Structural context indicators are used for research auditing and allocation simulation,
+not as protected-trait proxies for real-world underwriting.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A[Synthetic Business Data] --> B[Feature Pipeline]
+    B --> C[Random Forest Model]
+    C --> D[Capital Readiness Score]
+    C --> E[Local Explanation]
+    D --> F[Fairness Audit]
+    D --> G[Allocation Simulator]
+    F --> H[Research Dashboard]
+    G --> H
+    E --> H
+```
+
+See [Architecture](docs/ARCHITECTURE.md) and [Methodology](docs/METHODOLOGY.md).
+
+## Key capabilities
+
+- Reproducible synthetic U.S. small-business/startup data generation
+- Scikit-learn preprocessing and Random Forest classification pipeline
+- Holdout evaluation with ROC-AUC, accuracy, precision, recall, F1, and Brier score
+- Capital Readiness Score derived from predicted funding-success probability
+- Global feature-importance reporting
+- Applicant-level local sensitivity explanations
+- Structural-context fairness audit and selection-rate comparison
+- Efficiency-only and equity-aware capital-allocation simulation
+- Interactive Streamlit research dashboard
+- Automated tests and linting in GitHub Actions
+- Model card, citation metadata, contribution guide, and security policy
+
+## Python package
+
+The reusable research code lives in the `equitable_capital` Python package.
+
+After a release is published to PyPI, install it with:
+
+```bash
+pip install equitable-capital-optimization-ai
+```
+
+Example:
+
+```python
+from equitable_capital import (
+    allocate_capital,
+    fairness_audit,
+    generate_synthetic_startups,
+    train_model,
+)
+
+data = generate_synthetic_startups()
+result = train_model(data)
+audit = fairness_audit(result.scored_data)
+```
+
+For local development, install the repository in editable mode:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```bash
+git clone https://github.com/sakera023/equitable-capital-optimization-ai.git
+cd equitable-capital-optimization-ai
+python -m venv .venv
+```
+
+Activate the environment.
+
+**Windows**
+
+```bash
+.venv\Scripts\activate
+```
+
+**macOS/Linux**
+
+```bash
+source .venv/bin/activate
+```
+
+Install and run:
+
+```bash
+pip install -r requirements.txt
+streamlit run app.py
+```
+
+Development checks:
+
+```bash
+pip install -r requirements-dev.txt
+ruff check src tests app.py
+python -m pytest -q
+```
+
+## Repository structure
+
+```text
+.
+├── app.py
+├── pyproject.toml
+├── requirements.txt
+├── requirements-dev.txt
+├── Makefile
+├── src/
+│   └── equitable_capital/
+│       ├── __init__.py
+│       ├── allocation.py
+│       ├── config.py
+│       ├── data.py
+│       ├── explainability.py
+│       ├── fairness.py
+│       └── modeling.py
+├── tests/
+├── docs/
+├── .github/
+├── CITATION.cff
+├── CONTRIBUTING.md
+├── SECURITY.md
+├── CHANGELOG.md
+└── LICENSE
+```
+
+## Data design
+
+The repository uses **synthetic data by default**. This avoids exposing private
+financial records, makes the project reproducible, and prevents the demonstration from
+implying real-world predictive validity.
+
+Predictive features include revenue, growth, cash runway, employees, operating history,
+debt-service coverage, digital adoption, market demand, management capacity, requested
+capital, industry, and state.
+
+## Model evaluation
+
+The application reports ROC-AUC, accuracy, precision, recall, F1 score, and Brier score.
+These metrics evaluate the synthetic demonstration only.
+
+## Fairness and equity analysis
+
+A **structural barrier index** is built from contextual variables such as low-income
+area, rural area, limited finance access, and digital adoption.
+
+The index is reserved for post-model fairness diagnostics and research simulation of
+equity-aware allocation policies. It is not included in the predictive training
+features.
+
+## Reproducibility
+
+The synthetic data generator and model pipeline use explicit random seeds. Tests verify
+data ranges, prediction bounds, allocation-budget constraints, and fairness-audit
+outputs. CI runs on every push and pull request.
+
+## Research roadmap
+
+Planned extensions include gradient-boosted model benchmarks, probability calibration,
+SHAP, temporal/geographic validation, county-level opportunity maps, Census/SBA/CDFI
+public-data integrations, constrained optimization, and uncertainty analysis.
+
+See [Research Roadmap](docs/RESEARCH_ROADMAP.md).
+
+## Citation
+
+If you use the software, cite the repository metadata in [CITATION.cff](CITATION.cff).
+If you use the associated research concept, cite the publication separately and clearly
+distinguish research findings from this software prototype.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+Do not publish secrets, private financial information, or real applicant records in
+issues or pull requests. See [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Maintainer
+
+**Sakera Begum**

equitable_capital_optimization_ai-0.2.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "equitable-capital-optimization-ai"
+version = "0.2.0"
+description = "Research package for predictive capital-readiness analysis, fairness auditing, explainable AI, and equity-aware capital allocation."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Sakera Begum" }]
+keywords = [
+  "artificial-intelligence",
+  "machine-learning",
+  "predictive-analytics",
+  "entrepreneurship",
+  "small-business",
+  "capital-allocation",
+  "fairness",
+  "responsible-ai",
+  "explainable-ai",
+  "streamlit"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "numpy>=1.26,<3",
+  "pandas>=2.1,<4",
+  "plotly>=5.20,<8",
+  "scikit-learn>=1.4,<2",
+  "streamlit>=1.40,<2"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2,<2",
+  "pytest>=8,<10",
+  "ruff>=0.8,<1",
+  "twine>=5,<7"
+]
+
+[project.urls]
+Homepage = "https://github.com/sakera023/equitable-capital-optimization-ai"
+Repository = "https://github.com/sakera023/equitable-capital-optimization-ai"
+Issues = "https://github.com/sakera023/equitable-capital-optimization-ai/issues"
+Documentation = "https://github.com/sakera023/equitable-capital-optimization-ai/tree/main/docs"
+Publication = "https://www.researchgate.net/publication/410866072_An_AI-Powered_Framework_for_Equitable_Capital_Optimization_Leveraging_Predictive_Intelligence_to_Empower_Underserved_Entrepreneurial_Ecosystems_in_the_US"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["equitable_capital*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["equitable_capital"]

equitable_capital_optimization_ai-0.2.0/setup.cfg

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

equitable_capital_optimization_ai-0.2.0/src/equitable_capital/__init__.py

@@ -0,0 +1,25 @@
+"""Public API for the Equitable Capital Optimization research package."""
+
+from .allocation import allocate_capital, summarize_allocation
+from .data import generate_synthetic_startups
+from .explainability import explain_applicant
+from .fairness import fairness_audit, opportunity_gap
+from .modeling import (
+    ModelResult,
+    build_pipeline,
+    global_feature_importance,
+    train_model,
+)
+
+__all__ = [
+    "ModelResult",
+    "allocate_capital",
+    "build_pipeline",
+    "explain_applicant",
+    "fairness_audit",
+    "generate_synthetic_startups",
+    "global_feature_importance",
+    "opportunity_gap",
+    "summarize_allocation",
+    "train_model",
+]