Venture Pathfinder

Map your work. Find the white space. Build the next thing.

Venture Pathfinder scans your local git repositories and research assets, creates durable per-project profiles, loads them into a graph store, and generates venture paths from the patterns hidden across your body of work. Neo4j is the current local graph backend.

It is meant to become a strategic sparring partner: a central source of truth for what you have built, what keeps recurring, what can be reused, where the white space might be, and which new ventures could exist by combining pieces across your projects.

Roadmap

See ROADMAP.md for the product roadmap, target architecture, wisdom extraction layer, external opportunity radar, industry lenses, and strategic sparring workflow.

See PATTERN_ENGINE.md for the Fabric-inspired Pattern Engine design.

Acknowledgements

The Pattern Engine direction is inspired by Daniel Miessler's Fabric project and its community-maintained pattern library. Fabric popularized the idea of composable AI patterns as reusable thinking tools; Venture Pathfinder should preserve source, license, and author attribution for any imported or derived pattern work.

The codebase understanding and navigable knowledge-graph direction is inspired by Understand Anything by Lum1104. Venture Pathfinder should acknowledge that project when describing its detailed code-graph integration or importing .understand-anything/knowledge-graph.json outputs.

Brand Assets

• SVG mark
• 1024px PNG mark

Quick Start

For a copy-pasteable setup and self-improvement runbook, see QUICKSTART.md.

cd /Users/spider/REPOS/portfolio-mind
cp .env.example .env  # optional; the same oMLX defaults are built in
uv sync --dev --no-editable
uv run --no-editable pathfinder init
uv run --no-editable pathfinder scan ~/Code
uv run --no-editable pathfinder profile-all ~/Code
uv run --no-editable pathfinder report

Command Deck

Launch the local dashboard:

uv run --no-editable pathfinder dashboard

The command deck opens at http://127.0.0.1:8766. It provides a Situation Room, searchable Project Registry, Venture Radar, Pattern Matrix, local-model Sparring Room, background Operations deck, and Self-Improvement review. It reads the same profiles and reports as the CLI, so either interface can be used without migration.

The server is intentionally loopback-only. Long profiling, synthesis, reflection, and sparring work runs as a background job; the browser polls its status and refreshes the portfolio snapshot when it completes. To start without opening a browser:

uv run --no-editable pathfinder dashboard --no-browser

To use the local graph backend:

uv run --no-editable pathfinder graph-up
uv run --no-editable pathfinder ingest

To make Neo4j exactly match the current data/profiles/ set, removing stale projects from older scans:

uv run --no-editable pathfinder ingest --prune

Neo4j Browser for the current local backend will be available at:

http://localhost:7475

Default credentials:

username: neo4j
password: portfolio-mind

The local graph backend uses 7475 and 7688 by default to avoid colliding with another local Neo4j. Override with NEO4J_HTTP_PORT, NEO4J_BOLT_PORT, or NEO4J_URI.

Core Commands

uv run --no-editable pathfinder init
uv run --no-editable pathfinder scan ~/Code
uv run --no-editable pathfinder profile /path/to/repo
uv run --no-editable pathfinder profile-all ~/Code
uv run --no-editable pathfinder patterns
uv run --no-editable pathfinder ideas
uv run --no-editable pathfinder llm-ideas
uv run --no-editable pathfinder llm-ideas-population
uv run --no-editable pathfinder report
uv run --no-editable pathfinder improve run
uv run --no-editable pathfinder ask "What should I build next?"
uv run --no-editable pathfinder dashboard
uv run --no-editable pathfinder graph-up
uv run --no-editable pathfinder ingest
uv run --no-editable pathfinder graph-down

The old portfolio command remains installed as a compatibility alias. The provider-specific neo4j-up and neo4j-down commands also remain available, but graph-up and graph-down are the preferred generic commands.

Output

data/
  profiles/       Per-project JSON profiles
  raw/            Repo discovery output and cached analysis
  reports/        Markdown reports, idea JSON, and self-improvement runs
graph_store/
  neo4j/          Current local graph backend runtime folders

LLM Enrichment

The deterministic scanner works without a model. Venture synthesis and strategic sparring default to the same local setup as Book Buddy and Contingency Atlas:

provider:   oMLX (OpenAI-compatible, non-streaming)
endpoint:   http://127.0.0.1:8000/v1
model:      DeepSeek-V4-Flash-0731-MLX
API key:    test
timeout:    180 seconds
max tokens: 16384

The dashboard validates both endpoint reachability and the exact advertised model through authenticated GET /v1/models; it does not treat an open port as a healthy model server. Copy .env.example when local overrides are useful. Existing PROJECT_INTEL_*, legacy PORTFOLIO_MIND_*, and Book Buddy-style OMLX_* environment names remain supported.

To use a command adapter instead, configure any local command that reads a prompt from stdin.

Command adapter, for any local command that reads a prompt from stdin:

export PROJECT_INTEL_LLM_COMMAND='your-local-llm-command'
uv run --no-editable pathfinder ask "What should I build next?"
uv run --no-editable pathfinder llm-ideas --limit 10 --ingest

OpenAI-compatible HTTP adapter:

export PROJECT_INTEL_LLM_BASE_URL='http://localhost:11434/v1'
export PROJECT_INTEL_LLM_MODEL='llama3.1:8b'
export PROJECT_INTEL_LLM_API_KEY='not-needed'
uv run --no-editable pathfinder llm-ideas --limit 10 --ingest

For OpenAI:

export PROJECT_INTEL_LLM_BASE_URL='https://api.openai.com/v1'
export PROJECT_INTEL_LLM_MODEL='gpt-4.1-mini'
export PROJECT_INTEL_LLM_API_KEY='...'
uv run --no-editable pathfinder llm-ideas --limit 10 --ingest

LLM-generated ideas are written to:

data/reports/llm-product-ideas.md
data/reports/llm-product-ideas.json

To use the full saved project population without one giant prompt, run the batch-plus-final synthesis pipeline:

uv run --no-editable pathfinder llm-ideas-population \
  --batch-size 8 \
  --batch-idea-limit 15 \
  --batch-strategy hybrid \
  --bridge-batches 3 \
  --final-limit 45 \
  --ingest

This writes:

data/reports/llm-population-ideas.md
data/reports/llm-population-ideas.json
data/reports/llm-population-batch-ideas.json

For OMLX DeepSeek V4 Flash, .env sets PROJECT_INTEL_LLM_MAX_TOKENS=16384 so the HTTP adapter requests the model's maximum configured output budget.

Self-Improvement Loop

Run the deterministic self-improvement pass:

uv run --no-editable pathfinder improve run

This produces:

data/reports/self-improvement.md
data/reports/self-improvement.json

The report surfaces improvement signals, local graph research tasks, opt-in DDGS/GitHub research tasks, and ontology proposals that should be reviewed before they change the portfolio memory.

To ask the configured local model for a reflection pass:

uv run --no-editable pathfinder improve run --llm

To execute the top opt-in DuckDuckGo/DDGS web research tasks:

uv run --no-editable pathfinder improve run --duckduckgo --duckduckgo-limit 5

Provider errors are captured in the report instead of aborting the whole self-improvement run.

To store the self-improvement run in Neo4j:

uv run --no-editable pathfinder improve run --ingest

Understand Anything Integration

If a repository already has .understand-anything/knowledge-graph.json, Venture Pathfinder will read it and enrich the project profile with graph node types, edge types, architectural layers, and notable graph nodes.

This keeps the first version simple: Understand Anything can remain the detailed code scanner, while Venture Pathfinder becomes the cross-repo venture graph and idea layer.

Agentic Workflow Stance

The MVP is deterministic on purpose: scan, profile, ingest, mine, report.

When a richer agentic workflow is needed, the preferred orchestration layer is LangGraph StateGraph. DeepAgents should be reserved for cases that genuinely need longer-running autonomous decomposition rather than ordinary pipeline state.

Troubleshooting

If graph-up hangs, first check whether Docker can start any new container:

docker run --rm hello-world

If another Neo4j is already using 7474/7687, Venture Pathfinder should still work because it defaults to 7475/7688. To point Venture Pathfinder at an existing database instead:

NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=your-password \
  uv run --no-editable pathfinder ingest