README.md

---
title: DVNC.AI
emoji: 🧠
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 5.29.0
app_file: app.py
pinned: false
license: mit
short_description: Connectome-native scientific discovery workspace
---

# DVNC.AI

DVNC.AI is a connectome-native scientific discovery workspace designed to search, expand, and structure research topics into an interactive knowledge graph. The application supports topic-led discovery, paper lookup, document upload, graph expansion, and AI-assisted reasoning over research artifacts.

This repository currently runs as a **Gradio Space** with a root-level launcher file required by Hugging Face Spaces. The production UI lives in the nested application package, and the root `app.py` exists so the Space can boot correctly in the default Gradio runtime.

## Current repository layout

```text
.
├── app.py                  # Root Hugging Face launcher
├── app_old.py              # Legacy root app
├── requirements.txt        # Python dependencies for the Space
├── README.md
├── dvnc_ai_hf/             # Earlier app package
└── dvnc_ai_v2_hf/          # Current primary app package
```

## How the current Space starts

The Space is configured as a **Gradio Space**, which means Hugging Face expects a root `app.py` and installs dependencies from `requirements.txt`. The root launcher simply imports the active Gradio demo from `dvnc_ai_v2_hf.app` and starts it.

That pattern is intentional and should remain in place unless the Space is migrated to Docker.

## Supported architecture options

Two deployment patterns are supported for the next phase of development.

### Option 1: Gradio Space + external parser services

This is the simplest path and is the recommended option if the goal is to keep the current Space lightweight.

#### How it works

- Hugging Face runs the Gradio app using the root `app.py`.
- The main UI and orchestration logic live in `dvnc_ai_v2_hf/`.
- External scholarly/document parsing services are called over HTTP.
- PDF parsing can use a layered fallback:
  1. External GROBID endpoint for scholarly TEI extraction.
  2. Local Docling-based conversion for layout-aware parsing.
  3. Local PyMuPDF fallback for raw text extraction.

#### Recommended environment variables

- `ANTHROPIC_API_KEY` — required for Claude-powered reasoning.
- `GROBID_URL` — optional external GROBID server URL.
- `SEMANTIC_SCHOLAR_API_KEY` — optional, improves Semantic Scholar API access.
- `OPENALEX_EMAIL` — optional polite-pool identity for OpenAlex-style requests.
- `CROSSREF_MAILTO` — optional polite contact for metadata requests.

#### Recommended use cases

Use this mode if:
- the Space should remain a standard Gradio Space;
- the parser stack can live outside the Space;
- fast iteration is more important than bundling every service into one runtime.

### Option 2: Docker Space + bundled parsing stack

This is the recommended option if the application needs a first-class parsing service bundled with the app runtime.

#### How it works

- The Space is converted from `sdk: gradio` to `sdk: docker`.
- A custom `Dockerfile` starts the web app and any required background services.
- GROBID can run inside the same container or through an internal companion service.
- The app can expose a single user-facing web interface while running a richer backend.

#### Recommended use cases

Use this mode if:
- the Space should include GROBID directly;
- system packages or custom services are required;
- document parsing quality is a core product feature;
- the app needs more control over startup, ports, or service orchestration.

#### YAML for Docker migration

If the Space is migrated to Docker, replace the YAML block at the top of this README with:

```yaml
***
title: DVNC.AI
emoji: 🧠
colorFrom: indigo
colorTo: blue
sdk: docker
pinned: false
license: mit
short_description: Connectome-native scientific discovery workspace with bundled parsing and graph expansion services.
***
```

In Docker mode, `app_file` is no longer used because startup is controlled by the `Dockerfile`.

## Product direction

The target application architecture supports:

- **Research topic discovery** — search papers by topic or concept.
- **Paper lookup** — search by title, DOI, paper name, or direct link.
- **Autonomous discovery** — retrieve candidates from multiple scholarly sources.
- **User selection** — show candidate papers and let the user choose which ones enter the graph.
- **PDF upload** — allow users to upload papers directly.
- **Structured parsing** — extract title, abstract, sections, references, and metadata from documents.
- **Graph expansion** — turn selected or parsed documents into graph nodes and edges for the self-learning graph.

## Planned source connectors

The next implementation phase is designed to support a multi-source retrieval layer such as:

- Crossref for DOI and bibliographic metadata.
- OpenAlex for topic/title discovery and scholarly metadata enrichment.
- Semantic Scholar for academic graph enrichment and relevance ranking.
- arXiv for preprints and open metadata.
- Europe PMC for biomedical and life-science literature.
- Direct URL ingestion from paper landing pages and PDFs.

## Parser strategy

Document parsing should use a priority-based parser stack:

1. **GROBID** for scholarly PDF parsing into structured TEI/XML.
2. **Docling** for layout-aware extraction, tables, and document conversion.
3. **PyMuPDF** for fast native PDF text extraction fallback.

This approach keeps the PDF uploader in the product while improving document understanding significantly over plain text extraction alone.

## Running locally

### Gradio mode

Install dependencies:

```bash
pip install -r requirements.txt
```

Start the Space locally:

```bash
python app.py
```

If an external parser is used, export the parser endpoint first:

```bash
export GROBID_URL=http://localhost:8070
export ANTHROPIC_API_KEY=your_key_here
python app.py
```

### Docker mode

Once a `Dockerfile` is added, run locally with:

```bash
docker build -t dvnc-ai .
docker run -p 7860:7860 dvnc-ai
```

## Deployment notes

### For Gradio Spaces

Keep these files at the repository root:

- `README.md`
- `app.py`
- `requirements.txt`

Hugging Face Spaces expects the root application entrypoint for Gradio deployments.

### For Docker Spaces

Add:
- `Dockerfile`
- any startup scripts or service config files

Then switch the README YAML to `sdk: docker`.

## Secrets and configuration

At minimum, set:

- `ANTHROPIC_API_KEY`

Depending on the selected architecture, also set:

- `GROBID_URL`
- `SEMANTIC_SCHOLAR_API_KEY`
- source-specific API credentials if needed

## Development note

At present, `dvnc_ai_v2_hf/` should be treated as the primary active application package. The `dvnc_ai_hf/` and `app_old.py` files appear to represent earlier iterations and should be retained only if they are still needed for rollback or reference.