Impact Vision
Open-source AI-powered impact measurement and SDG alignment engine for VC/impact investment funds
Ask AI about Impact Vision
Powered by Claude Β· Grounded in docs
I know everything about Impact Vision. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Impact Vision
Open-source AI-powered impact measurement and SDG alignment agent for VC and impact investment funds.
Built on OpenHarness, Impact Vision ships a conversational AI agent, a CLI, a REST API, an MCP server, a Streamlit dashboard, and a single-file Web Console β all backed by the same engine with deep expertise in GIIN's IRIS+ framework, UN SDGs, the 5 Dimensions of Impact, and 10+ ESG / regulatory frameworks (ISSB, ESRS, SFDR, TCFD, SASB, GRI, PCAF, SBTi, EU Taxonomy, TNFD, CDP).
Release history lives in CHANGELOG.md. Strategy and engineering plans live in docs/.

Screenshots
![]() AI agent with full impact measurement toolkit | ![]() Due diligence questions + 5-Dimension scoring |
![]() Recommended IRIS+ metrics by category | ![]() HTML report: 5-Dimension radar chart with scores |
![]() SDG alignment scoring (17 goals, official UN colors) | ![]() Sector-specific opportunities & risks analysis |
Try it yourself: See a sample HTML report generated for a pig farm in Malaysia.
What is Impact Investing?
Impact investing means investing with the intention to generate positive, measurable social and environmental impact alongside a financial return. Unlike traditional investing (financial return only) or philanthropy (social good only), impact investing seeks both.
Key concepts Impact Vision helps with:
| Concept | What it means |
|---|---|
| IRIS+ | The "GAAP for impact" -- ~787 standardized metrics for measuring social/environmental outcomes (maintained by GIIN) |
| SDGs | 17 UN Sustainable Development Goals (e.g., No Poverty, Clean Energy, Climate Action) with 169 targets |
| 5 Dimensions | The standard framework for assessing impact quality: What outcome? Who benefits? How much? Would it happen anyway? What could go wrong? |
| Impact DD | Due diligence focused on whether an investment will actually generate the claimed impact |
| ESG | Environmental, Social, Governance -- risk management frameworks (SASB, GRI, TCFD, SFDR, EDCI, UNPRI, ISSB, ESRS) |
| NESTA Evidence | 5 levels rating how strong the evidence is: Level 1 (narrative) to Level 5 (rigorous RCT) |
Core Use Case
Upload a pitch deck or investment memo and Impact Vision will:
- Extract and classify impact claims (outcome / output / activity / intent / risk)
- Map claims to relevant IRIS+ metrics from the 787-metric catalog
- Detect SDG goal/target alignment from the content
- Run an impact DD checklist (122 questions across 34 categories from GIIN, PCV, Seraf, IMP, AFME + sector-specific for 15 sectors)
- Assess evidence strength using NESTA Standards of Evidence (levels 1-5)
- Auto-extract a Company model for immediate use with downstream assessment tools
- Compare against sector benchmarks from GIIN survey data
- Suggest the most important follow-up questions for the investment team
- Generate reports in HTML (with Plotly charts), XLSX, CSV, JSON, or text
Using Impact Vision in your fund workflow? See the Fund Manager Quick Reference for a Python-first 60-second SDK walkthrough (deal scoring, IC memo, DD questionnaire, portfolio roll-up, LP calendar).
Quick Start (from scratch)
1. Prerequisites
You need Python 3.11+ and Git. Check if they're installed:
python --version # should show 3.11 or higher
git --version # any recent version
If not installed: Python | Git
2. Clone and install
git clone https://github.com/joejoe168168/impact-vision.git
cd impact-vision
Create a virtual environment (recommended):
python -m venv .venv
# Activate it:
# Windows PowerShell: .venv\Scripts\Activate.ps1
# Windows CMD: .venv\Scripts\activate.bat
# Mac/Linux: source .venv/bin/activate
Install the package:
pip install -e ".[dev]"
After this, you'll have two commands available: impact-vision and iv (shorthand).
'impact-vision' is not recognized? Run the auto-fix script:# Windows PowerShell powershell -ExecutionPolicy Bypass -File scripts\add-to-path.ps1 # Windows CMD scripts\add-to-path.bat # Mac/Linux bash scripts/add-to-path.shImportant: After running the script, you must close and reopen your terminal (CMD/PowerShell/Terminal) for the PATH change to take effect. Then try
impact-vision --help.Alternative: Use
python -m openharnessinstead (works without PATH changes):python -m openharness --help python -m openharness catalog stats python -m openharness dd list
3. Set up an LLM provider
The AI agent needs a language model. We recommend OpenRouter for beginners -- it's free to start and gives you access to many models.
Option A: OpenRouter (recommended -- free models available)
Step 1. Create an OpenRouter account:
- Go to openrouter.ai and click Sign Up (Google or GitHub login works)
- Go to openrouter.ai/keys and click Create Key
- Copy the key (starts with
sk-or-...)
Step 2. Run the interactive setup wizard:
impact-vision setup
The wizard will guide you through these prompts:
? Choose a provider workflow:
Anthropic-Compatible API Claude / Kimi / GLM / MiniMax
> OpenAI-Compatible API OpenAI / OpenRouter <-- select this
...
? Choose an OpenAI-compatible provider:
OpenAI official
> OpenRouter <-- select this
? Base URL: https://openrouter.ai/api/v1 <-- press Enter (default)
? Default model: openai/gpt-oss-120b:free <-- type a model name
? Enter API key for OpenRouter: sk-or-your-key-here <-- paste your key
Done! You can now start the agent (Step 4).
Free models (verified May 2026): Browse the live list at openrouter.ai/models?q=free. Impact analysis needs tool calling, so stick with these:
Model Context Why we recommend it openai/gpt-oss-120b:free131K OpenAI open-weight MoE, native tool use, strong reasoning nvidia/nemotron-3-super-120b-a12b:free1M 1M-token window for long decks, strong multi-step reasoning z-ai/glm-4.5-air:free131K Hybrid-thinking MoE, cheap + fast, tool-calling google/gemma-4-31b-it:free262K Native function calling, multimodal, Apache 2.0 OpenRouter rotates free endpoints monthly β if a model 404s, re-run
impact-vision setupand pick another from the live list.
Option B: Anthropic (Claude Sonnet) -- best quality for impact analysis
- Go to console.anthropic.com, create an account
- Go to API Keys and create a key
- Run the wizard and choose Anthropic-Compatible API > Claude official:
impact-vision setup
- Paste your API key when prompted (Claude Sonnet is the default model)
Option C: OpenAI (GPT-5)
- Go to platform.openai.com/api-keys, create a key
- Run the wizard and choose OpenAI-Compatible API > OpenAI official:
impact-vision setup
- Paste your API key when prompted
Option D: Local Ollama (free, runs on your machine, no internet needed)
- Install Ollama from ollama.com
- Pull a model:
ollama pull llama3.2 - Run setup:
impact-vision ollama-setup --model llama3.2
No API key needed -- everything runs locally on your GPU/CPU.
| Provider | Best for | Cost |
|---|---|---|
| OpenRouter | Trying multiple models, free tier | Free + pay-per-use |
| Anthropic (Claude Sonnet) | Best impact analysis quality | Pay-per-use |
| OpenAI (GPT-5) | General purpose | Pay-per-use |
| Ollama (local) | Privacy, offline use | Free (your hardware) |
Model quality note: Impact analysis requires models that support tool calling (function calling). Free models vary in quality -- some may not follow the impact expert persona or use the analysis tools correctly. For best results:
- Recommended paid: Claude Sonnet or GPT-5 for production DD work
- Recommended free:
openai/gpt-oss-120b:free,nvidia/nemotron-3-super-120b-a12b:free,z-ai/glm-4.5-air:free- May struggle: Very small models (<9B) or models without tool-calling support
4. Start the AI agent
impact-vision
Try asking:
- "Analyze this pitch deck" (provide a path to a PDF)
- "What SDGs does a solar energy company align with?"
- "Run a 5-dimension assessment for a fintech serving 50,000 clients"
5. Try the CLI tools (no API key needed)
These commands work without any LLM setup:
# See all available commands
impact-vision --help
# Browse IRIS+ metrics (all 787 metrics included out of the box)
impact-vision catalog stats
impact-vision catalog search "climate"
impact-vision catalog search "gender"
# List ESG/sustainability frameworks
impact-vision framework list
# Quick multi-framework scan of a company description
impact-vision framework scan "Solar energy company providing clean power to 50,000 rural households"
# Cross-reference a metric across all frameworks
impact-vision framework xref OI4112
# Browse the Due Diligence checklist (122 questions across 34 categories)
impact-vision dd list
impact-vision dd categories
# Analyze text against the DD checklist
impact-vision dd analyze "We serve 45,000 clients across 3 countries. Our NPS score is 72."
6. Update the IRIS+ Catalog (optional)
All 787 IRIS+ 5.3c metrics are already bundled and work out of the box. If GIIN releases a newer version of the catalog:
- Download the new Excel file from GIIN IRIS+ (free registration)
- Place it in
data/raw/ - Run:
impact-vision catalog load # Parse Excel into JSON cache
impact-vision catalog stats # Verify metric count
7. Launch the dashboard (optional)
streamlit run src/openharness/dashboard/app.py
Opens a web dashboard at http://localhost:8501 with 5 tabs: Assessment, IRIS+ Catalog, DD Checklist, Framework Scan, and Portfolio.
Quick reference
| Command | What it does |
|---|---|
iv --help | Show all commands |
iv catalog stats | Show catalog statistics |
iv catalog search "query" | Search IRIS+ metrics |
iv framework list | List all supported ESG / regulatory frameworks |
iv framework scan "text" | Quick multi-framework scan |
iv framework xref OI4112 | Cross-reference a metric |
iv dd list | Show all 122 DD questions |
iv dd categories | List DD categories |
iv dd analyze "text" | Check text against DD checklist |
iv ollama-setup | Configure local LLM |
iv serve-mcp | Start MCP server for AI agents (39 impact tools + 5 resources) |
iv serve-web | Start Web Console + REST API at http://127.0.0.1:8787 |
iv | Start interactive AI agent |
(iv is a shorthand for impact-vision)
Usage
Impact Vision ships 39 impact agent tools covering the full investment lifecycle
β pre-screen, due diligence, IC memo, portfolio monitoring, LP reporting,
assurance, and post-exit review. Below are common prompts you can paste
into the interactive agent (or the Web Console at
http://127.0.0.1:8787). The agent will pick the right tools for you.
Analyzing a Pitch Deck
The primary workflow: upload a PDF and let the agent analyze it.
> Analyze this pitch deck for impact: /path/to/pitch_deck.pdf
The agent will use the pitch_deck_analyze tool which:
- Extracts text from all PDF pages
- Identifies impact claims and maps them to IRIS+ metrics and SDGs
- Runs the full DD checklist against the document
- Presents addressed questions vs. gaps
- Suggests follow-up questions to ask the investment team
Follow-up prompts that chain the v3/v4 tools on the same deal:
> Run a 5-dimension assessment for BrightPath Finance with the claims you just extracted
> Draft a Theory of Change for BrightPath and link it to IRIS+ metrics
> Score greenwashing risk per-claim and show which claims need verification
> Start an engagement workspace for BrightPath at the "scoping" stage
> Attach a data pack: these metrics came from the audited FY24 statements
> Build a completeness scorecard for the data pack and produce coaching cards
> Run the AI extraction review queue over the claims you flagged as low-confidence
Browsing the IRIS+ Catalog
> Search for IRIS+ metrics related to financial inclusion
> Show me metrics mapped to SDG 7 (Clean Energy)
> What metrics are tagged with the "What" dimension?
> Get details for metric OI1479
Running a DD Checklist
> Show me the full impact DD checklist
> Which DD questions are about risk assessment?
> Analyze this document against the DD checklist: /path/to/memo.pdf
SDG Alignment Scoring
> Map BrightPath Finance to SDG goals. They report metrics PI4060, OI8869, OI6213...
> Which SDGs does this company align with based on their financial inclusion work?
5-Dimension Assessment
> Score this company on the 5 Dimensions of Impact
> What are the gaps in the "Contribution" dimension?
Cross-Reference Lookup
> Look up cross-references for IRIS+ metric OI4112
> Search cross-references for "gender" across all frameworks
> What's the GRI equivalent of SFDR PAI indicator #1?
Generating Reports
> Generate an HTML impact report for BrightPath Finance (includes Plotly charts)
> Export the assessment as XLSX for our LP report
> Generate a report with sector benchmark comparison
HTML reports include an Interactive Score Improvement section -- check boxes for practices your organization follows (e.g., "We track beneficiaries", "We have a Theory of Change") and watch scores update in real-time with a before/after radar chart.
Improving Scores Through Q&A
Ask the agent to help you improve your impact scores interactively:
> Help me improve my impact scores for this pig farm
> Ask me questions to strengthen the assessment
The agent will:
- Identify your weakest scoring dimensions
- Ask targeted questions (e.g., "How many direct beneficiaries?", "Do you track emissions?")
- Map your answers to IRIS+ metrics
- Re-run the assessment and show exactly how your answers improved each dimension
ESG Framework Assessment
> Scan this company against all ESG frameworks
> What are the material SASB topics for a fintech company?
> Assess TCFD alignment for our climate disclosure
> Check SFDR PAI compliance for the portfolio
> Show the EDCI 2026 private-markets KPI fields and which we're reporting
> Run a UNPRI self-assessment for our fund
> Assess ISSB IFRS S1 general disclosure readiness
> Check ISSB IFRS S2 climate disclosure for our carbon data
> Run EU CSRD/ESRS double materiality assessment
> Classify our fund under SFDR Article 6/8/9
Theory of Change Assessment
> Assess our fund's Theory of Change against RS Group's Blended Value principles
> Check our ToC against the GIIN IRIS+ checklist
> Help me develop a Theory of Change for our microfinance investment
> List all RS Group principles and GIIN ToC steps
Greenwashing & Compliance Checks
> Run a greenwashing check on this pitch deck
> Assess EU Green Claims Directive compliance
> Check UK FCA Anti-Greenwashing Rule alignment
> Compute the Green Authenticity Index and Cheap Talk Index for this report
Impact Verification & Product Passport
> Check our readiness for IFC OPIM verification
> Import Digital Product Passport data from this JSON file
> Map DPP categories to IRIS+ and ESRS metrics
LP DDQ Export
> Generate an ILPA DDQ response for BrightPath Finance
> Create a GIIN/IRIS+ impact report template
> Export EDCI annual survey as XLSX: output_path="edci_survey.xlsx"
Portfolio Batch Analysis
> Analyze this portfolio CSV file: examples/sample_portfolio.csv
> Generate aggregated SDG coverage for the portfolio
> Run portfolio roll-up with fund-level 5D scores
> Generate an LP report for our fund
> Show impact attribution by sector and geography
Pipeline Management
> Add EcoFinance to the pipeline at screening stage
> Transition EcoFinance to DD in progress with rationale "Strong SDG alignment"
> Show the pipeline dashboard
> List all companies at IC review stage
Continuous Monitoring
> Set quarterly monitoring for EcoFinance
> Record metric PI4060 = 15000 for EcoFinance
> Check alerts for our portfolio
> Run a full re-assessment for EcoFinance
Guided Assessment
> Start a screening assessment for BrightPath Finance
> What's the next step in the assessment?
> Submit company description data for the current step
Stakeholder Voice & Beneficiary Feedback
> Build a Lean Data survey template for smallholder farmers in Kenya
> Register GDPR-compliant consent records for 50 beneficiaries
> Score feedback quality and link responses to our outcome claims
Climate Accounting (Scope 1/2/3 + PCAF)
> Calculate a Scope 1/2 GHG inventory from this fuel + electricity data
> Apply emission factor catalog v2 with uncertainty bands
> Run PCAF financed-emissions attribution for the loan book
> Check SBTi 1.5 Β°C alignment
AI Extraction Review & Evidence Governance
> Show the AI extraction review queue for BrightPath
> Auto-approve claims above 0.85 confidence that cite audited sources
> Flag any claim without a source URL for human review
> Open a verification workspace for the assurer and share only approved evidence
LP Narrative & Q&A (grounded in verified data)
> Generate an LP quarterly narrative for the Inclusive Finance fund
> Answer LP question "what % of beneficiaries are women" using only approved data
> Export the Q&A transcript with citations for the LPAC meeting
Portfolio Natural-Language Query
> What was the average CO2e intensity across the climate portfolio last year?
> Top 5 companies by beneficiary reach, verified data only
> Compare SDG 5 coverage between Fund I and Fund II
Exit Impact Assessment (OPIM Principle 8)
> Score exit-impact durability for Solar Co with acquirer profile "strategic utility"
> List unmitigated risks and build a 12-month exit impact plan
Consultant Engagements (v4 workspace)
The v4 engagement suite is a single tool (engagement_suite) that covers
scoping, data rooms, ToC/KPI design, reporting studios, training, public
website output, and the three-pillar assurance bundle.
> Create an engagement workspace for "Acme Solar Advisory Q2" at scoping stage
> Build a proposal with a fixed-fee rate card and send it for client signature
> Design a Theory of Change + KPI tree and validate it against IRIS+
> Build a client data room, score completeness, and issue coaching cards
> Move the draft report from "in_review" to "published" and log the state change
> Issue a readiness badge once training modules + diagnostic are complete
> Sign the final assurance bundle (evidence graph + audit trail + workspace) with HMAC
Single-Prompt Mode
For CI/CD or scripting:
impact-vision -p "Search IRIS+ catalog for climate-related metrics"
CLI Reference
impact-vision (or the iv shorthand) exposes seven top-level
subcommand groups plus three service commands. Run any command with
--help for full flags.
# Interactive agent
impact-vision # Start interactive agent session
impact-vision -p "your prompt" # Single prompt, then exit
impact-vision --model opus # Use a specific model
# Provider / auth setup
impact-vision setup # Interactive provider wizard (OpenRouter/Claude/OpenAI/Ollama)
impact-vision ollama-setup --model llama3.2
impact-vision provider list | use | add | edit | remove
impact-vision auth login | status | logout | switch | copilot-login | codex-login | claude-login
# IRIS+ catalog
impact-vision catalog load [EXCEL_PATH] [--force]
impact-vision catalog stats
impact-vision catalog search "climate"
# ESG / sustainability frameworks
impact-vision framework list
impact-vision framework scan "company description"
impact-vision framework xref OI4112
# Due-diligence checklist (122 questions / 34 categories)
impact-vision dd list [--category "What (Outcomes)"]
impact-vision dd categories
impact-vision dd analyze "text or /path/to/doc.txt"
# Service surfaces
impact-vision serve-mcp # MCP server (stdio)
impact-vision serve-mcp --transport sse --port 8765 # MCP over SSE
impact-vision serve-web # Web Console + REST API (http://127.0.0.1:8787)
# Developer utilities
impact-vision mcp list | add | remove # Manage MCP server configs
impact-vision plugin list | install | remove # Manage entry-point plug-ins
impact-vision cron list | add | remove | run # Cron scheduler for background jobs
Architecture
impact-vision/
βββ src/openharness/
β βββ impact/ # Impact measurement engine
β β β
β β β # --- Core engine ---
β β βββ models.py # Pydantic: Metric, Company, Assessment, SDG, ImpactClaim
β β βββ catalog.py # IRIS+ 5.3c Excel ETL (263-column parser)
β β βββ database.py # In-memory MetricStore (search/filter/stats)
β β βββ sdg_taxonomy.py # 17 SDG Goals + 169 Targets reference
β β βββ five_dimensions.py # What/Who/HowMuch/Contribution/Risk scoring
β β βββ sdg_mapper.py # Per-goal SDG alignment scorer (0-100)
β β βββ gap_analysis.py # Core Metric Set coverage analysis
β β βββ dd_checklist.py # DD question engine + NESTA evidence scoring
β β βββ benchmarks.py # Sector benchmarks for 18 sectors
β β βββ greenwashing.py # Greenwashing detection (standard + Green Claims + FCA + NLP)
β β βββ risk_opportunity.py # Risk/opportunity (likelihood Γ severity)
β β βββ storage.py # SQLite persistence for assessments
β β β
β β β # --- Fund workflow (v0.8+) ---
β β βββ fund_thesis.py # Fund impact thesis, IC gate, adverse thresholds
β β βββ ic_memo.py # IC memo rendering (MD/HTML/DOCX/PPTX)
β β βββ deal_gate.py # Deal scorecard (pass/warn/fail gate)
β β βββ portfolio_rollup.py # Capital-weighted portfolio roll-up
β β βββ lp_calendar.py # 12-month LP reporting calendar
β β βββ tenancy.py # Multi-tenant + RBAC
β β βββ plugins.py # Entry-point plug-in discovery
β β βββ signed_feed.py # Hash-chained LP report feed (HMAC)
β β βββ lp_portal.py # ILPA-compatible LP portal
β β βββ marketplace.py # Thesis marketplace (publish/subscribe)
β β β
β β β # --- Scientific rigor + primary data (v0.14.0) ---
β β βββ extractors/ # Pluggable claim extractors (regex/LLM)
β β βββ toc_graph.py # Theory-of-Change graph + Mermaid renderer
β β βββ counterfactual.py # GIIN COMPASS additionality templates
β β βββ bayes.py Β· meta_analysis.py Β· spillover.py Β· sroi.py Β· causal.py
β β βββ geospatial.py Β· surveys.py Β· worker_voice.py Β· ecosystem_services.py
β β βββ registries.py # Verra/Gold Standard/Puro/BioCredits
β β βββ returns.py # MOI + impact-adjusted IRR
β β βββ external_benchmarks.py # GIIN Compass peer quartiles
β β βββ blended_finance.py # IL-Loans, SOC/DIB, impact carry
β β βββ assurance.py Β· csrd_wizard.py Β· issb_reporting.py Β· soc2_checklist.py
β β βββ audit_trail.py # Hash-chained lifecycle events
β β βββ i18n.py Β· fx.py Β· regulatory_packs.py Β· branding.py
β β β
β β β # --- v2 institutional backbone (v0.13+) ---
β β βββ metric_records.py # Canonical MetricRecord contract
β β βββ investee_collection.py # Questionnaire schema + submission lifecycle
β β βββ climate_accounting.py # Scope 1/2 GHG inventory
β β βββ evidence_graph.py # Claimβmetricβtargetβevidence lineage
β β βββ standards_registry.py # Versioned standards metadata
β β βββ roadmap_v2.py # Collection / disclosure / assurance helpers
β β β
β β β # --- v3 Trust Infrastructure (v0.15.0) ---
β β βββ emission_factors.py # Versioned factors + sensitivity bands
β β βββ stakeholder_voice.py # Lean Data + GDPR/PDPA consent
β β βββ evidence_workflow.py # AI extraction review queue
β β βββ verification_workspace.py # Assurer workspace + findings
β β βββ lp_narrative.py # LP narrative + Q&A (approved-data only)
β β βββ greenwashing_reviewer.py # Per-claim explainable review
β β βββ portfolio_nlq.py # NL portfolio queries + ApprovedDataPolicy
β β βββ exit_impact.py # OPIM P7 exit-impact scoring + P8 learning context
β β β
β β β # --- v4 Engagement Suite (latest) ---
β β βββ engagements/
β β β βββ workspace.py # EngagementWorkspace + artifact audit hook
β β β βββ proposal.py # Proposal builder + e-signature
β β β βββ toc_builder.py # Wraps toc_graph + metric_recommender
β β β βββ data_room.py # Completeness scorecard + coaching cards
β β β βββ value_creation.py # Scenario + business case + risk scoring
β β β βββ reporting_studio.py # Draft β review β published state machine
β β β βββ training.py # Modules + diagnostic + readiness badge
β β β βββ website.py # Public diagnostic + lead capture
β β β βββ copilot.py # Governed AI: review queue + safe answer
β β β βββ regulatory.py # Jurisdiction profiles + SFDR classification
β β β βββ verification_bundle.py # 3-pillar signed assurance bundle (HMAC)
β β β
β β βββ report_templates/ # Jinja2-based HTML report templates
β β βββ frameworks/ # 10 ESG/sustainability frameworks
β β β βββ sasb.py Β· gri.py Β· tcfd.py Β· sfdr_pai.py Β· edci.py
β β β βββ unpri.py Β· theory_of_change.py Β· issb_ifrs_s1.py Β· issb_ifrs_s2.py
β β β βββ esrs.py Β· ifc_opim.py Β· pcaf.py Β· sbti.py Β· eu_taxonomy.py
β β β βββ tnfd.py Β· cdp.py
β β β βββ cross_reference.py # 59 cross-framework metric mappings
β β βββ mcp_server.py # MCP server (FastMCP)
β β βββ sdk.py # High-level ImpactVision SDK facade
β β
β βββ tools/impact/ # 39 LLM-callable impact agent tools (see "Tools" below)
β βββ api_gateway/router.py # FastAPI REST API
β βββ web/ # Single-file Web Console + SSE streaming
β βββ dashboard/app.py # Streamlit 5-tab dashboard
β βββ skills/bundled/content/ # Agent knowledge (markdown)
β βββ prompts/system_prompt.py # Impact Vision persona + instructions
β βββ cli.py # CLI (7 subcommand groups + serve-mcp / serve-web)
βββ data/
β βββ raw/ # IRIS+ Excel file (not committed)
β βββ processed/ # JSON catalog cache (auto-generated)
β βββ dd_checklist.yaml # 122 DD questions / 34 categories
β βββ scoring_config.yaml # Sector baselines + keyword boosts
β βββ sdg_keywords.yaml # SDG keyword mappings for 20+ sectors
β βββ core_metric_set_per_sdg.yaml # Curated SDG core metric set
β βββ fund_thesis.*.yaml # Default + 4 regional thesis packs
β βββ i18n/ # 6 languages (en/es/fr/pt/zh/ar)
βββ docs/
β βββ fund-manager-guide.md # Python SDK walkthrough for funds
β βββ roadmap-v3.md / -v3-implementation.md
β βββ roadmap-v4.md # Consultant-led engagement suite
β βββ cursor-integration.md # Cursor/VS Code MCP setup
βββ examples/ # Sample company, portfolio, MCP configs
βββ tests/ # Test suite (impact + v2 + v3 + v4)
βββ .github/workflows/ci.yml # Import smoke + tests + ruff
DD Checklist
The built-in due diligence checklist includes 122 questions across 34 categories, sourced from:
- GIIN Impact Toolkit - The Impact Due Diligence Guide
- Pacific Community Ventures - Impact DD Emerging Best Practices
- Seraf Toolbox - Impact Investing Due Diligence Checklist
- Impact Management Project (IMP) - Five Dimensions of Impact
- AFME / Neotas / OECD - ESG Due Diligence frameworks
- Sector-specific: 15 sectors including fintech, healthcare, agriculture, energy, education, manufacturing, transport, construction, tourism, retail, mining, media, professional services, waste management, and ICT
Each addressed question is assessed using NESTA Standards of Evidence (levels 1-5):
| Level | Description |
|---|---|
| 1 | Narrative / anecdotal only (self-reported, no data) |
| 2 | Output data (quantified activities, e.g. # served) |
| 3 | Outcome data measured (pre/post, surveys, tracked KPIs) |
| 4 | Controlled comparison (quasi-experimental, benchmarks) |
| 5 | Rigorous evaluation (RCT, independent audit, causal attribution) |
Questions are organized into 34 categories (18 core + 15 sector-specific + 1 SDG):
Core Categories (18)
| Category | Qs | Covers |
|---|---|---|
| Impact Thesis & Theory of Change | 4 | Mission, theory of change, business model alignment |
| What (Outcomes) | 4 | Specific outcomes, positive/negative impacts, outcome data |
| Who (Stakeholders) | 5 | Beneficiaries, underserved status, baseline, feedback |
| How Much (Scale) | 5 | Reach, depth, duration, growth, quantitative metrics |
| Contribution | 4 | Additionality, counterfactual, evidence, investor contribution |
| Risk | 5 | Evidence risk, execution risk, external risk, mitigation, impact washing |
| Measurement Systems | 6 | IMM systems, IRIS+ alignment, data frequency, third-party audit |
| Governance/ESG | 5 | Board oversight, environmental/labor/ethics policies, incentives |
| SDG Alignment | 1 | Specific goals and targets |
| Negative Impact | 3 | Do-no-harm assessment, grievance mechanisms |
| Exit Sustainability | 3 | Impact continuity, mission lock, acquirer risk |
| Financial Sustainability | 5 | Revenue model, impact-return tension, grants dependency, pricing |
| Team & Capability | 4 | Founder experience, community ties, key person risk |
| Market & Context | 4 | Market size, regulation, systemic barriers, competition |
| Product/Service Design | 4 | User-centered design, safety, privacy, affordability |
| Supply Chain | 3 | ESG practices, forced/child labor risk, environmental footprint |
| Stakeholder Voice | 3 | Feedback mechanisms, co-design, transparency |
| Investor Alignment | 3 | Impact covenants, value-add beyond capital, portfolio fit |
Sector-Specific Categories (15 sectors)
| Sector | Qs | Covers |
|---|---|---|
| Fintech | 5 | Over-indebtedness, client protection, effective interest rate, digital literacy, responsible AI |
| Healthcare | 5 | Health regulations, patient safety, clinical efficacy, affordability, data privacy |
| Agriculture | 5 | Farmer income, sustainable farming, climate resilience, food safety, land tenure |
| Energy | 5 | CO2e avoided, energy access, e-waste, affordability, grid reliability |
| Education | 5 | Learning outcomes, underserved learners, pedagogy, digital safety, employment |
| Manufacturing | 2 | Circular economy, pollution prevention, worker safety |
| Transport & Logistics | 2 | Emissions reduction, last-mile accessibility |
| Construction | 3 | Green building standards, affordable housing, waste diversion |
| Tourism | 2 | Cultural preservation, community benefit-sharing |
| Retail | 3 | Ethical sourcing, plastic waste reduction, fair labor |
| Mining & Extractives | 3 | Tailings management, community consent (FPIC), rehabilitation |
| Media | 2 | Misinformation safeguards, digital inclusion |
| Professional Services | 2 | Pro-bono access, diversity metrics |
| Waste Management | 3 | Recycling rates, informal worker integration, hazardous waste |
| ICT | 3 | E-waste, data sovereignty, digital divide |
Frameworks & Standards
All frameworks below are exposed via the framework_assess tool, the
MCP server, the REST API, and the Python SDK. Every framework ships with
cross-references to IRIS+ metric IDs via the shared
cross_reference module (59 concept mappings).
| Category | Framework | Coverage |
|---|---|---|
| Core taxonomy | GIIN IRIS+ 5.3c | ~787 metrics, SDG mappings, 5-Dimension tags |
| UN SDGs | 17 Goals, 169 Targets | |
| Impact DD Checklist | 122 questions / 34 categories (GIIN, PCV, Seraf, IMP, AFME + 15 sectors) with NESTA evidence (1-5) | |
| Sector Benchmarks | 18 sectors (GIIN survey data) with aggregated 5D scores and coverage | |
| Cross-Reference Mapping | 59 concepts mapped across IRIS+/GRI/EDCI/SFDR PAI/SASB/TCFD/ESRS/ISSB/PCAF/SBTi/TNFD/CDP/EU Taxonomy | |
| ESG disclosure | SASB | 17 industries, 77+ material topics |
| GRI | 34 standards (Universal + Topic), 120+ disclosures | |
| TCFD / IFRS S2 | 4 pillars, 11 disclosures, scenario analysis, Scope 1/2/3 | |
| EDCI | 2026 PE/VC KPI fields, including non-core cybersecurity testing | |
| UNPRI | 6 Principles, 27 actions | |
| Theory of Change | RS Group 8 Blended Value Principles + GIIN 8-step ToC Checklist | |
| ISSB IFRS S1 | General sustainability disclosure (4 pillars) | |
| ISSB IFRS S2 | Climate-related disclosures | |
| EU CSRD / ESRS | 11 standards, double-materiality assessment | |
| Regulatory | SFDR | 14 mandatory + 9 optional PAI indicators, Article 6/8/9 classification, deadline scheduler |
| EU Taxonomy | 6 environmental objectives, DNSH + Minimum Safeguards | |
| UK FCA Anti-Greenwashing Rule | Fair/clear/not-misleading assessment | |
| EU Green Claims Directive | Evidence, comparability, third-party verification | |
| EU Digital Product Passport (ESPR) | Import + map to IRIS+/ESRS/SDG | |
| Per-jurisdiction packs | EU-SFDR, EU-CSRD, UK-FCA-SDR, US-SEC-ESG, HK-HKEX-ESG, AU-AASB-S2, ISSB-global | |
| Climate & nature | PCAF | Financed-emissions attribution, sector defaults, weighted data quality |
| SBTi (Net-Zero Standard v1.2) | 1.5 Β°C pathway, Scope-3 materiality, 2050 cap | |
| TNFD v1 | 14 LEAP / pillar disclosures | |
| CDP | Climate / water / forests questionnaire intake | |
| GHG Protocol | Scope 1/2 inventory (Scope 3 via PCAF) with versioned factor catalog | |
| Impact management | IFC OPIM | 9-principle verification readiness + Principle 8 exit-impact |
| SROI | Deadweight / attribution / displacement / drop-off adjustments | |
| MOI + Impact-adjusted IRR | Newton-Raphson, optional shadow price | |
| Greenwashing & NLP | Standard greenwashing scoring | Vague-language + quantitative-evidence checks |
| Green Authenticity Index (GAI) | Ratio of substantive to vague claims | |
| Cheap Talk Index (CTI) | Forward-looking vs. evidenced statements | |
| Per-claim explainable reviewer | concrete / mixed / vague / buzzword_only classification + severity | |
| Assurance | ISAE 3000 / AA1000 | Management-assertion + subject-matter + evidence register |
| SOC 2 Type II / ISO 27001 | Starter control set with readiness report | |
| Verification workspace | Finding lifecycle + threaded comments (v0.15.0) | |
| 3-pillar assurance bundle | HMAC-signed evidence graph + audit trail + workspace (v4) |
Agent Tools (39)
All tools below are exposed through the default OpenHarness tool registry
and openharness.tools.impact, so the interactive agent, Web Console,
REST API, and MCP server see the same surface.
Pre-screen & core assessment (7)
| Tool | Description |
|---|---|
pitch_deck_analyze | PDF/TXT/MD intake with impact-claim extraction + Company model |
iris_catalog | IRIS+ catalog search, browse, filter by SDG/theme |
sdg_mapper | SDG alignment scoring with theme inference and evidence chains |
five_dimension_assess | 5-Dimension assessment with additionality & counterfactual prompts |
gap_analysis | Metric gap analysis vs Core Metric Set |
impact_metric_recommender | Recommend IRIS+ metrics by theme, SDG, and sector |
impact_data_quality | Quality score for reported metrics (placeholders, unknown IDs) |
Due diligence & evidence (5)
| Tool | Description |
|---|---|
dd_checklist | 122-question DD checklist, document analysis, and targeted suggestions |
document_analysis | Multi-document comparison, change detection, claim verification |
guided_assessment | Step-by-step workflow with deal-stage templates |
verification_prep | IFC OPIM 9-principle readiness assessment |
product_passport | EU Digital Product Passport import and IRIS+/ESRS mapping |
Risk & credibility (4)
| Tool | Description |
|---|---|
greenwashing_detect | Composite screen (5 sub-scores) + Green Claims / FCA / GAI / CTI |
greenwashing_reviewer | Per-claim explainable review with severity + governance metadata |
impact_risk_opportunity | 14 risk categories on a likelihood Γ severity matrix |
exclusion_screening | UNGC, weapons, fossil-fuel exclusion lists |
Frameworks & reporting (4)
| Tool | Description |
|---|---|
framework_assess | Multi-framework ESG assessment (all frameworks in the table above) |
cross_reference | Cross-framework metric lookup (59 mappings) |
impact_report | Interactive HTML reports + XLSX/CSV/JSON/text/PDF |
lp_ddq_export | LP DDQ responses in ILPA, GIIN, EDCI, SFDR formats |
Decision workflow β v5 (2)
| Tool | Description |
|---|---|
decision_workflow | Quick screen, IC memo proof bundle, deal comparison, and LP readiness |
regulatory_calendar | Jurisdiction-specific reporting deadlines for fund and engagement planning |
Portfolio workflow (5)
| Tool | Description |
|---|---|
portfolio_analyze | Batch analysis, capital-weighted roll-ups, benchmarking |
portfolio_query | Natural-language portfolio queries (ApprovedDataPolicy-gated) |
pipeline | 8-stage investment pipeline with transition tracking |
monitoring | Continuous monitoring, metric updates, alerts, re-assessment |
trend_analysis | Time-series metric trend analysis with trajectory projection |
Stakeholder voice & narrative (4)
| Tool | Description |
|---|---|
beneficiary_feedback | Import and analyze beneficiary feedback data |
stakeholder_voice | Lean Data templates + GDPR/PDPA consent + feedbackβclaim links |
improvement_advisor | LLM-guided improvement recs, peer insights, SDG opportunities |
narrative | Impact narrative drafting (exec summary, key findings, case studies) |
Trust infrastructure β v3 (4)
| Tool | Description |
|---|---|
emission_factors | Versioned factor catalog, sensitivity bands, inventory repricing |
evidence_review | AI extraction review queue with policy-driven auto-approval |
verification_workspace | Assurer workspace with finding lifecycle and threaded comments |
lp_narrative | LP narrative + Q&A constrained to verified data with citations |
Exit & assurance (1)
| Tool | Description |
|---|---|
exit_impact | OPIM Principle 8 scoring + exit plan |
Consultant engagement suite β v4 (3)
| Tool | Description |
|---|---|
engagement_workspace | Engagement lifecycle (scoping β delivery β closeout) + artifact audit |
toc_builder | ToC canvas + logic-chain validator + multi-framework KPI generator (wraps v3 toc_graph + metric_recommender) |
engagement_suite | Umbrella tool for Tracks 3-10: proposal, data room, value-creation, reporting studio, training/readiness, public website, governed AI copilot, regulatory deadlines, 3-pillar assurance bundle |
Streamlit Dashboard
For a visual alternative to the CLI agent:
streamlit run src/openharness/dashboard/app.py
The dashboard has 5 tabs:
- Company Assessment: Input company data, see 5-Dimension radar chart, SDG bar chart, and gap analysis
- IRIS+ Catalog: Browse, search, and filter the 787-metric catalog
- DD Checklist: Browse questions, paste text to check coverage
- Framework Scan: Run TCFD, SFDR PAI, EDCI, and SASB assessments
- Portfolio: Upload CSV for batch analysis with aggregated charts
Web Console (power-user UI)
For a browser-native surface to every tool β useful when you want the full 39-tool set at your fingertips rather than Streamlit's 5 curated tabs β run the web console:
# Start the console + REST API (defaults to http://127.0.0.1:8787)
impact-vision serve-web
# Or directly via uvicorn
uvicorn openharness.web.app:app --host 127.0.0.1 --port 8787
The console is a single self-contained HTML file (no build step, no JS framework) that sits on top of the existing FastAPI gateway:
- Lists every impact tool in a searchable sidebar (
Ctrl/β+Kto focus). - Derives typed forms from
/openapi.jsonandPOSTs to/api/v1/*. - Shows JSON results in a syntax-highlighted pane, with copy / save buttons.
- Persists every run to
localStorageso you can re-hydrate old invocations. - Optional bearer-token box for
IMPACT_VISION_API_KEY-protected deployments. - Links to the live
/docs(Swagger) and the GitHub repo.
Development
# Install with dev dependencies
pip install -e ".[dev]"
# Run all tests
python -m pytest tests/ -v
# Focused subsets
python -m pytest tests/test_impact.py -v # engine + frameworks
python -m pytest tests/test_v4_tracks_3_to_10.py -v # v4 engagement suite
# Import smoke checks (verifies all package exports work)
python scripts/check_imports.py --all
# Lint
ruff check src/
GitHub Actions runs import smoke, full tests, and ruff on every push/PR.
MCP Server (Use with Claude, Cursor, VS Code)
Impact Vision can run as an MCP server, exposing the full impact tool surface and 5 read-only resources to any MCP-compatible AI client.
impact-vision serve-mcp # stdio (desktop clients)
impact-vision serve-mcp --transport sse --port 8765 # SSE (remote clients)
Use stdio for local desktop clients such as Claude Desktop, Cursor, and VS Code. Use SSE when the MCP server is started separately and clients connect over HTTP.
Cursor / VS Code Setup
Add to .cursor/mcp.json:
{
"mcpServers": {
"impact-vision": {
"command": "impact-vision",
"args": ["serve-mcp"]
}
}
}
Claude Desktop Setup
Copy examples/claude_desktop_config.json to your Claude Desktop config directory.
MCP Resources
| Resource URI | Purpose |
|---|---|
impact://catalog/stats | IRIS+ catalog counts, categories, and themes |
impact://dd-checklist/categories | DD checklist categories and question counts |
impact://frameworks/list | Supported ESG / impact frameworks |
impact://cross-reference/{metric_id} | Cross-framework mapping for one metric |
impact://sdg/goals | UN SDG goal reference data |
See docs/cursor-integration.md for the full setup guide and client-specific notes.
REST API
FastAPI REST gateway backing the Web Console, MCP server, and third-party integrations:
# Start the API server
uvicorn openharness.api_gateway.router:app --reload
# Authenticated (set env var for production)
IMPACT_VISION_API_KEY=your-secret-key uvicorn openharness.api_gateway.router:app
Key endpoints: /api/v1/score, /api/v1/sdg-map, /api/v1/greenwashing,
/api/v1/report, /api/v1/pipeline, /api/v1/batch, and more.
See the auto-generated OpenAPI docs at /docs.
Roadmap
Strategy and engineering plans live in docs/:
docs/roadmap-v2.mdβ April 2026 institutional-readiness plan (data contracts, investee collection, climate accounting, LP reporting, assurance controls, causal impact, governed AI).docs/roadmap-v3.md/-v3-implementation.mdβ Trust infrastructure (evidence review, verification workspace, LP narrative, portfolio NLQ, exit impact). Shipped.docs/roadmap-v4.mdβ Consultant-led engagement suite (Tracks 3-10). Backend shipped; frontend + paid-data wiring deferred to Wave 5.ROADMAP.mdβ historical engineering record.CHANGELOG.mdβ release notes.
Contributing
Have ideas? Open an issue or submit a PR!
License
MIT License. See LICENSE for details.
Acknowledgments
- AvantFaire Investment Management -- the first impact investment company in Hong Kong that nurtured the creator's passion for impact measurement
- GIIN for IRIS+ and the Impact Due Diligence Guide
- Pacific Community Ventures for DD emerging best practices
- Seraf for the impact investing DD checklist
- Impact Management Project for the 5 Dimensions of Impact
- OpenHarness for the agent infrastructure






