Command Line Interface

Nancy Brain provides a comprehensive command-line interface for managing your knowledge bases. All commands are automatically documented below.

Installation

pip install nancy-brain

CLI Reference

nancy-brain

Nancy Brain - Turn GitHub repos into AI-searchable knowledge bases.

Usage:

nancy-brain [OPTIONS] COMMAND [ARGS]...

Options:

  --version  Show the version and exit.
  --help     Show this message and exit.

nancy-brain add-article

Add a PDF article to the configuration.

Usage:

nancy-brain add-article [OPTIONS] ARTICLE_URL ARTICLE_NAME

Options:

  --category TEXT     Category to add article to
  --description TEXT  Description of the article
  --help              Show this message and exit.

nancy-brain add-repo

Add a repository to the configuration.

Usage:

nancy-brain add-repo [OPTIONS] REPO_URL

Options:

  --category TEXT  Category to add repo to
  --help           Show this message and exit.

nancy-brain build

Build the knowledge base from configured repositories.

The build command validates config/repositories.yml (and config/articles.yml if provided) before starting. If validation fails, the command prints detailed errors and exits with a non-zero status.

Usage:

nancy-brain build [OPTIONS]

Options:

  --config TEXT                 Repository config file
  --articles-config TEXT        PDF articles config file
  --embeddings-path TEXT        Embeddings output path
  --force-update                Force update all repositories
  --dry-run                     Show what would be done without executing the
                                build
  --dirty                       Leave raw repos and PDFs in place after build
                                (don't cleanup)
  --summaries / --no-summaries  Generate Gemini summaries during build
                                (defaults to ENABLE_DOC_SUMMARIES env)
  --batch-size INTEGER          Index documents in batches (requires
                                embeddings.upsert support). 0 = disable
                                batching.
  --max-docs INTEGER            Stop after indexing this many document chunks
                                (for testing / limiting resource use). 0 = no
                                limit.
  --category TEXT               Limit build to a single repository category
                                (as defined in repositories.yml)
  --help                        Show this message and exit.

nancy-brain explore

Explore the knowledge base document tree structure.

Usage:

nancy-brain explore [OPTIONS]

Options:

  --embeddings-path TEXT  Embeddings path
  --config TEXT           Config path
  --weights TEXT          Weights path
  --prefix TEXT           Path prefix to filter results
  --max-depth INTEGER     Maximum depth to traverse
  --max-entries INTEGER   Maximum number of entries to show
  --help                  Show this message and exit.

nancy-brain init

Initialize a new Nancy Brain project.

This command creates a minimal config/ directory with a repositories.yml file to get you started. Edit the file and then run nancy-brain build.

Usage:

nancy-brain init [OPTIONS] PROJECT_NAME

Options:

  --help  Show this message and exit.

nancy-brain search

Search the knowledge base.

Usage:

nancy-brain search [OPTIONS] QUERY

Options:

  --limit INTEGER         Number of results
  --embeddings-path TEXT  Embeddings path
  --config TEXT           Config path
  --weights TEXT          Weights path
  --help                  Show this message and exit.

nancy-brain serve

Start the HTTP API server.

Usage:

nancy-brain serve [OPTIONS]

Options:

  --host TEXT     Host to bind to
  --port INTEGER  Port to bind to
  --help          Show this message and exit.

nancy-brain ui

Launch the web admin interface.

Usage:

nancy-brain ui [OPTIONS]

Options:

  --port INTEGER  Port to run Streamlit on
  --help          Show this message and exit.

Configuration Files

Nancy Brain uses YAML configuration files:

repositories.yml

# Repository categories and sources
microlensing_tools:
  - name: MulensModel
    url: https://github.com/rpoleski/MulensModel.git
  - name: pyLIMA
    url: https://github.com/ebachelet/pyLIMA.git

general_tools:
  - name: numpy
    url: https://github.com/numpy/numpy.git

articles.yml

# PDF articles to index
research_papers:
  - name: "Microlensing Survey Methods"
    url: "https://arxiv.org/pdf/astro-ph/0123456.pdf"
    description: "Comprehensive survey methods review"

reviews:
  - name: "Neural Networks in Astronomy"
    url: "https://example.com/nn-astro.pdf"

weights.yaml

# File type weights for search ranking
file_weights:
  ".py": 1.2    # Boost Python files
  ".md": 1.0    # Standard weight for docs
  ".rst": 1.0   # Sphinx documentation
  ".txt": 0.8   # Lower weight for plain text

Tips and Best Practices

Project Setup

Always start with nancy-brain init project-name
Configure config/repositories.yml before building
Use meaningful category names for organization

Building Knowledge Bases

Use --force-update when repositories have been updated
Large repositories may take time to process
Monitor disk space for embeddings storage

Searching Effectively

Use specific technical terms for better results
Combine multiple keywords: "neural networks optimization"
Use --limit to get more diverse results

Exploring Content

Start broad with nancy-brain explore
Use --prefix to focus on specific areas
Adjust --max-depth based on repository structure

Development Workflow

nancy-brain init my-project
Edit config/repositories.yml
nancy-brain build
nancy-brain search "test query"
nancy-brain ui for interactive exploration

Troubleshooting

Common Issues

Build fails with permission errors:

# Ensure write permissions for embeddings directory
chmod -R 755 knowledge_base/

Search returns no results:

# Verify embeddings were built successfully
ls -la knowledge_base/embeddings/
nancy-brain explore --max-entries 5

UI won't start:

# Install Streamlit dependency
pip install streamlit
nancy-brain ui

Memory issues during build: - Process smaller repositories first - Use --articles-config separately for PDFs - Monitor system resources during build

For more troubleshooting tips, see Troubleshooting Guide.