Update README.md

Updated Readme.md

README.md

@@ -1,23 +1,209 @@
 ---
 title: DVNC.AI
 emoji: 🧠
-colorFrom: gray
-colorTo: indigo
+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
 
-This root patch lets the existing nested `dvnc_ai_v2_hf/` folder run on Hugging Face Spaces by providing a root-level `app.py` entrypoint, which Hugging Face requires for Gradio Spaces.[cite:166][cite:163]
+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.
 
-## Required existing folder
-This patch assumes the repository already contains the uploaded folder:
-- `dvnc_ai_v2_hf/`
+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.
 
-The bridge file imports the `demo` object from `dvnc_ai_v2_hf.app` so the existing implementation can remain in place while the Space launches from the repository root.[cite:166][cite:323]
+## Current repository layout
 
-## Required secret
-Set `ANTHROPIC_API_KEY` in the Space secrets for live Claude calls.[cite:294][cite:300]
+```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.