AppImage (recommended): This is a full self-contained package.

chmod +x Bango_*_amd64.AppImage
./Bango_*_amd64.AppImage

If AppImage won't launch, ensure FUSE is installed: sudo apt install libfuse2 (Debian/Ubuntu) or the equivalent for your distribution.

DEB package:

sudo apt install ./Bango_*_amd64.deb

or

sudo dpkg -i Bango_*_amd64.deb
sudo apt-get install -f   # resolve any missing dependencies

Linux does not enforce code signing, so no additional security bypass steps are needed.

1. Download Bango_3.5.4_x64-setup.exe (or the .msi for enterprise installs).
2. Double-click to run the installer.
3. Windows SmartScreen will show a warning: "Windows protected your PC"
   • Click "More info"
   • Click "Run anyway"
4. Follow the setup wizard to complete installation.

If your organization blocks unsigned installers via Group Policy, use the MSI package or build from source.

1. Download Bango_3.5.4_aarch64.dmg.
2. Double-click the .dmg file to open it.
3. Drag Bango to the Applications folder.
4. On first launch, macOS Gatekeeper will block the app: "Bango cannot be opened because the developer cannot be verified."

To bypass Gatekeeper:

• Option A: Right-click (or Control-click) the app, select "Open", then click "Open" again in the confirmation dialog.
• Option B: Run the following command in Terminal:

xattr -cr /Applications/Bango.app

After bypassing once, the app will launch normally on subsequent opens.

• Import RIS and BibTeX bibliography files with full metadata (title, abstract, authors, year, DOI, journal, keywords, and more)
• Import multiple files into a single project with automatic re-deduplication
• Capacity guard: enforces a 10,000 article project limit; imports that would exceed this are blocked
• Preview parsed records and manually deselect individual articles before confirming import
• Export the included list in valid RIS format, with AI-generated tags (KW), reasoning notes (N1), user notes (NO), and inclusion/exclusion labels (C1 as JSON)
• Full project export/import as a single .bango.json file (API keys excluded; bibliometrics, wiki content, and AI summaries are regenerable and excluded)
• Import Zotero collections from a locally running Zotero desktop client via its local API, including subcollections and PDF attachment copies
• Zotero export: push articles back into Zotero from the Export dialog, with a DOI diff preview classifying items as missing, already present, or no-DOI
• Journal index enrichment: bundled journal reference data matches journal names to ISSN/eISSN and publisher metadata during import and restore

• Multi-strategy matching: DOI exact match, title+year exact (>=95% similarity), fuzzy title+year (70 to 94%), author+title partial
• Levenshtein distance-based title comparison with normalization
• Auto-merge exact duplicates; flag fuzzy matches for side-by-side manual review
• Non-duplicate articles are promoted directly to the Working list on import
• Duplicates are placed in a separate Duplicates list with duplicateOf references
• Cross-status dedup protection: articles already in Working, Included, or Rejected are never affected by new duplicate imports

• Define research aims as a list of discrete text entries
• Define inclusion and exclusion criteria as discrete entries, each with a priority level
• Priority levels: Critical, High, Standard, Low, or Optional
• Deterministic conflict resolution: highest-priority matched rule wins; ties favor inclusion; no match defaults to exclude
• Inline editing: double-click any aim or criterion text to edit it in place (Enter saves, Shift+Enter for newline, Esc cancels, empty commit deletes)
• Custom screening rules (Section 4 in the Criteria editor): free-text combinatorial rules (AND/OR gates, hard exclusions, conditional inclusion) that are injected into every screening prompt
  • References criteria by their global number so "criterion 3" is unambiguous to the LLM, the user, and the reasoning

• Configure connections to hosted LLMs (OpenAI, Anthropic, Google, Mistral AI, z.ai) or local setups (llama.cpp, Ollama, LM Studio), plus any OpenAI-compatible endpoint
• AI evaluates article abstracts in batches (1 to 5 articles per call) for high throughput
• Returns structured JSON with decision, reasoning paragraph, matched criteria, suggested tags, extracted terms, and confidence score
• Background batch processing with configurable concurrency (default: 3) and request delay (default: 500ms)
• Exponential backoff on rate limits; malformed responses flagged as screening errors
• Optional max_articles cap to process a bounded subset in a single run

Three screening modes (selectable in Settings):

• Enhanced and Two-stage modes apply per-article only when full text is attached; articles without full text fall back to abstract-only screening
• A per-article chunk budget (default 2400 words) prevents any single article from blowing the context window
• At screening start, previously-attached PDFs without chunks are backfilled transparently (no LLM call)
• Immediate stop: cancel an in-flight screening run within milliseconds
• Smart error recovery: transient failures leave articles unscreened for the next run, while authentication failures stop the run immediately

Non-English articles can be translated to English before AI workflows consume them. This is a Plan-A permanent rewrite: the working article row and chunks hold English text after translation, while originals are preserved in a separate archive.

• Auto-translate (Settings toggle, default off): non-English articles are automatically enqueued for translation during import and screening
• Manual translate button on the article detail header for any non-English article (works regardless of auto-translate setting)
• Two job kinds (selected automatically):
  • MetadataOnly: translates title + abstract (for articles without full text)
  • FullText: translates title + abstract + full text + chunks, then re-chunks the English result
• 10-language section classification: Academic section headings (Abstract, Introduction, Methods, Results, Discussion, Conclusion, References) are recognized in French, Spanish, Japanese, Chinese, German, Russian, Portuguese, Italian, Arabic, and Turkish
• Queue worker: a dedicated background worker with its own SQLite connection processes translation jobs sequentially without blocking UI command handlers
• Crash recovery: on app startup, stranded jobs from a crashed session are marked failed; the user selectively retranslates via the manual button
• TRANSLATED badge appears on the article detail header once translation is complete
• Originals preserved in article_original_content + article_original_chunks tables

• Tags: content-category labels (e.g., "machine-learning", "clinical-trial") AI suggests from RIS keywords and user criteria; user can add, edit, delete
• Labels: workflow markers (e.g., "priority-read", "disputed") AI generates from inclusion/exclusion criteria; user can expand and modify
• Standard taxonomy surfacing: the standalone suggest_tags command injects 20 curated study-type tags (systematic-review, meta-analysis, rct, cohort-study, etc.) and suggest_labels injects 12 workflow-state labels (priority-read, strong-methodology, borderline, etc.)
• Backend sanitizer: all tag/label names are sanitized to <=35 chars, lowercase, hyphenated; inclusion:/exclusion: prefixes are stripped; truncation happens at the last word boundary (never mid-word)
• Inline editing: double-click any tag/label chip to edit it in place (blur saves, Esc cancels)
• Tags and labels generated in a pre-screening pass; user reviews before AI screening begins
• Full manual editing: override any AI decision, adjust tags and labels, move articles between lists
• Sort, filter, merge by use any Tag or Label

All modules operate on your included articles and imported citation/reference data. A single Normalize transaction builds the analytical data layer; modules then become available from the Bibliometrics dashboard.

1. Co-Authorship Network - Maps collaborative relationships between researchers. Full and fractional edge counting, Louvain community detection, ForceAtlas2 layout. Export as PNG or GEXF.
2. Citation Network - Directed graph showing which articles cite which others, with main-path analysis (Search Path Count). Trace ancestry or progeny of any node. Unmatched references appear as dashed leaf nodes.
3. Keyword Co-Occurrence - Discover thematic clusters from five combinable sources: metadata keywords, AI noun phrases, tags, labels, and user-added terms.
4. Publication Timeline - Stacked bar charts of publications, references, and citations by year, plus a growth-rate sparkline. CSV and SVG export.
5. Author Productivity Ranking - Sortable table with h-index, i10-index, g-index, plus first/last/solo author counts. Google Scholar lookup icons. Detail slide-over with per-article breakdown.
6. Co-Citation Analysis - On-demand computation with four normalization modes (Raw, Cosine, Jaccard, Pearson). Dual visualization: interactive network graph and sortable heatmap. Scope: included or all articles.

• Cluster Thematic Analysis: select one cluster in the co-authorship or keyword network and let the LLM explain what its members share, with clickable article and author links
• Google Trends panel: a bottom drawer in the keyword view embeds Google Trends timeseries and geo-map charts for selected keywords (mostly blocked by Google at this time but you can open in separate window)

• Track backward references (articles cited by a paper) and forward citations (articles that cite a paper)
• Import reference/citation detail via RIS or BibTeX for any article
• N1 citation count extraction: automatically parses Total Times Cited and Cited Reference Count from Web of Science notes during standard imports
• Promotion workflow: unmatched reference papers with abstracts can be promoted to full articles in the Working list
• Match status states: unmatched, matched (linked to existing library article), imported, not_in_library
• Citation Chaser integration: external tool output can be imported by placing DOI-keyed RIS files in the {storage_root}/ris/ directory and running the Batch Import Processor

• Standard four-phase PRISMA 2020 flow diagram with exact record counts
• Optional exclusion reason breakdown (user-controlled toggle)
• Rendered as SVG; exportable as SVG and PNG

• Attach .pdf or .txt files to any article
• Text extraction: PDF text parsed and cached in the full_text field; TXT read as plain text
• CJK PDF mojibake recovery: when a CJK PDF font lacks a ToUnicode CMap, the extractor detects the common Latin-1 misinterpretation and re-decodes the bytes to correct Unicode (Shift-JIS, EUC-JP, CP949, GB18030)
• Section-aware chunking: extracted text is classified into sections (Methods, Results, Discussion, etc.) and chunked for semantic retrieval, table/figure caption extraction, and screening evidence
• Original file copied to a configurable storage root (defaults to ~/Documents/Bango/fulltext/)
• Inline PDF reader: render attached PDFs directly inside the article detail panel
• AI Summary (schema v2 superset): the generate_article_ai_summary command can produce section-typed facts (study_design, sample_size for Methods; effect_size, confidence_interval for Results) when section summaries are enabled
• Figure/Table descriptions: generate_figure_descriptions extracts figure/table captions from the full text and sends them in one batched LLM call to produce grounded descriptions, rendered as grids/blocks in the summary view

Bango generates and maintains a local-first Obsidian-style Markdown knowledge base from your included article corpus. The wiki lives on disk under {storage_root}/wiki-root/ and is fully navigable inside the app.

Page types:

• Author pages: metrics (h-index, citations, papers/year), publications list with footnotes, research areas, frequent collaborators
• Synthesis pages: one per included article with an AI summary, digest, key insights, and concept links
• Concept hubs: top terms from the corpus linking to their articles and co-occurring concepts
• Methods hubs: study-design hubs (RCT, cohort, meta-analysis, etc.) with a curated lexicon for canonicalization
• Source pages: one per user-uploaded external document (PDF/TXT/web) for first-class wiki node integration

Features:

• Deterministic 5-layer pre-seed matrix: author, synthesis, concept, methods, and source pages are generated deterministically before the LLM runs, so the wiki backbone exists regardless of which model is used
• Parallel chunked ingest: large corpora are split into batches and processed concurrently for faster generation
• Multi-batch consolidation: cross-batch duplicate pages are merged deterministically with link rewriting
• FTS5 BM25 search: full-text search index over all wiki pages
• Graph visualization: sigma + ForceAtlas2 layout, color-coded by page type, with hover tooltips
• RAG chat: token-budgeted chat over the wiki FTS5 index with section-aware citations
• External-edit drift detection: detects when external programs (e.g., Obsidian) edit wiki files and re-indexes transparently without re-running the LLM
• Static-site export: exports the wiki as a self-contained static website (HTML + CSS + JS + Markdown) in a .zip file; article references resolve to synthesis pages or metadata-only stubs (copyright-safe, no full text included)
• Obsidian vault export: exports the wiki as a ready-to-open Obsidian vault .zip with all UUIDs pre-processed (synthesis pages renamed to author-year-title slugs, wikilinks/footnotes/frontmatter rewritten, Home.md index + .obsidian/ graph color config included); reachable from the Wiki toolbar Actions menu and the global Export dialog
• Back/Forward navigation: browser-style page navigation with platform-aware keyboard shortcuts (Alt+Left/Alt+Right on Windows/Linux, Cmd+[/Cmd+] on macOS)

• Conversational interface to query your systematic review project
• Two retrieval modes (mutually exclusive):
  • Article RAG: Retrieval-Augmented Generation over your criteria, research aims, and article abstracts
  • Wiki RAG: BM25 FTS5 search over the LLM Wiki knowledge base, with section-aware citations
• Answers include source-citation badges linking directly to referenced articles or wiki pages
• Wiki-sourced assistant bubbles render with [[wikilink]] and [^art-id] resolution
• A Wiki toggle button in the chat view switches between modes (visible only when the wiki is initialized with pages)

• Paste any paragraph of prose (for example from a manuscript) and Bango finds which articles in your library support or contradict each claim
• Two modes: whole-block (one result set) or per-statement (the LLM splits the prose into up to 5 claims matched independently)
• Three-layer pipeline: semantic embedding prefilter, token-Jaccard passage extraction, then LLM classification (validating or opposing, out-of-context flag, confidence score)
• One-button flow: missing embeddings are prepared automatically with live progress, cancel support, and a model-mismatch regeneration dialog
• Copy matched citations in APA, MLA, Chicago, IEEE, or AMA style
• Accessed as a third toggle in the Chat view alongside Articles and Wiki

• Per-article, per-chunk embedding vectors power bounded cosine-recall semantic search and act as the Citation Finder prefilter
• Generated automatically in the background after AI summaries, full-text chunk rebuilds, and batch import Phase 5
• A triple-state capability flag detects provider support during Test Connection; providers without embeddings (like Anthropic) are skipped gracefully
• Per-row staleness tracking re-embeds only changed text, and switching models offers scoped regeneration

Generates database-ready Boolean search strings for 8 academic databases from the research aims and inclusion/exclusion criteria you have already defined in the Criteria view. Copy-only - it builds text strings you paste into each database's own search interface.

• Supported databases: PubMed, Scopus, Web of Science, Cochrane Library, EBSCOhost, JSTOR, ScienceDirect, arXiv
• PICO breakdown: concept blocks with 3-8 synonyms each
• Per-database syntax: the system prompt embeds a full cheatsheet (operators, field codes, format conventions) so the LLM produces syntactically correct strings per platform
• Warnings: surfaces concerns like missing concepts or the Semantic Scholar non-Boolean advisory
• Surfaced inline as a collapsible card in the Criteria editor, gated on having aims and LLM configured

Scans the Bango Documents directory for files produced by external tools and imports them by DOI-keyed file matching. Runs as a background task with live progress and cancel support.

5-phase pipeline:

1. Full Text (Phase 1): scans fulltext/ for {doi}.pdf / .txt files and attaches them to matching articles
2. Citations (Phase 2): scans ris/ for {doi}_references.ris, _citations.ris, .ris, .bib files and imports references/citations
3. Translations (Phase 3): enqueues FullText translation jobs for non-English newly-attached articles (only when auto-translate is enabled)
4. AI Summaries (Phase 4): generates AI summaries for newly-attached articles without an existing summary (only when LLM is configured)
5. Embeddings (Phase 5): generates semantic vectors for included articles with newly attached full text (only when the provider supports embeddings)

Each phase skips articles that already have the relevant data, making the pipeline idempotent.

• Generates a structured AI summary of included articles: key themes, research trends, methodological strengths, common weaknesses, and literature gaps
• Section-aware summaries (schema v2): when section summaries are enabled, the LLM returns section-typed facts (study_design, sample_size, effect_size, confidence_interval) for Methods/Results/Discussion
• Figure/Table descriptions: extracts figure/table captions and generates grounded descriptions in one batched LLM call per article
• Evidence enrichment: optional summary_evidence_mode setting (abstract_only or with_summary_facts) enriches the literature review prompt with AI summary facts

Research Gap Analysis:

• A "Research Gap Report" button generates a corpus-wide Markdown gap-analysis report covering five sections: Thematic Coverage, Identified Gaps, Methodological Landscape, Future Research Directions, and References
• Shares the same toolbar, gating, and export buttons (Citation Style, Copy, Export Markdown, Export PDF) as the literature review
• Mirrors the batching strategy (split + synthesize) when the corpus exceeds 80% of the context window
• Persisted in a single-row table; cleared on project restore

• Every state change, tag/label edit, and AI decision logged with timestamp and source
• Audit entry coalescing: rapid same-type edits within a 5-minute window update the existing entry instead of spamming duplicates
• Per-article history timeline view
• System-wide errors (scraping, LLM config) logged to the Diagnostics screen
• Full-text search across title and abstract fields
• Sort by title, publication year, date added, or AI confidence score
• Filter by status, tags, labels, matched criteria, publication year range, and manual override status
• Filter by DOI (partial match) with an "Only no DOI" mode for data cleanup, plus NOT-negation on tag/label pills to exclude matches
• Inline metadata editing: double-click the title, journal (with journal-index autocomplete), authors, year, DOI, or keywords to edit in place
• Permanent delete: hard-delete an article and all related data, including on-disk files, in one transaction
• Bulk edit selected articles: many articles can be managed in bulk, e.g. export, include, exclude
• Keyboard navigation: arrow keys browse the article list and move between articles in the detail panel