🏛️ Institutional Shadow

AI-Powered Institutional Memory for BC Nonprofits

When a coordinator leaves a nonprofit, their institutional knowledge leaves with them. Institutional Shadow captures that knowledge passively — from documents the org already produces — and makes it queryable through a plain-language chat interface.

Built for the SAP Hackathon: Strengthening BC's Nonprofit Workforce.

---

Quick Start

1. Clone and enter the repo

git clone <your-repo-url>
cd institutional-shadow

2. Create a virtual environment

python3 -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

cp .env.example .env
# Edit .env — add your OpenAI API key at minimum

5. Verify everything works

python verify_setup.py

All checks should pass before proceeding.

6. Ingest seed documents

python -m src.ingest

7. Run the app

streamlit run app.py

Opens at http://localhost:8501

---

Project Structure

institutional-shadow/
├── app.py                  # Streamlit UI entry point
├── verify_setup.py         # Pre-flight check script
├── requirements.txt
├── .env.example
├── src/
│   ├── __init__.py
│   ├── config.py           # All configuration and prompts
│   ├── vectorstore.py      # ChromaDB ↔ HANA factory
│   ├── ingest.py           # Document ingestion pipeline
│   └── query.py            # RAG chain + persona modes + cache
└── data/
    └── seed/
        ├── emails/
        ├── meeting_notes/
        ├── grants/
        └── handover_memos/

---

Switching to SAP HANA Cloud

1. Set VECTOR_BACKEND=hana in .env
2. Fill in HANA_HOST, HANA_PORT, HANA_USER, HANA_PASSWORD
3. Re-run python -m src.ingest to populate HANA
4. Restart streamlit run app.py

---

Seed Document Naming

All seed documents use the format: YYYY-MM-DD_description.txt

The date prefix is extracted by the ingestion pipeline and used for knowledge-decay detection.