Skip to content

Local Development Setup

Development environment for AI Research Assistant: Python 3.13, Pipenv, pytest, and optional docs tooling.

Source: Pipfile, README.md, src/__main__.py.

Prerequisites

Requirement Notes
Python 3.13+ Pinned in Pipfile [requires]
Pipenv Virtualenv and lockfile management
Git Clone the repository

For LLM development with Ollama, run Setup system — Quick start. Cloud-only development needs API keys only.

Initial setup

git clone https://github.com/Ndevu12/Research_Assistant_Model.git
cd Research_Assistant_Model
pip install pipenv
pipenv install --dev
cp .env.example .env   # optional

pipenv install --dev installs:

  • Runtime packages ([packages]): pydantic-ai, aiohttp, sentence-transformers, hdbscan, etc.
  • Dev packages ([dev-packages]): mkdocs, mkdocs-material, mkdocs-mermaid2-plugin

Optional API development:

pipenv install fastapi uvicorn

Run the application

Always use Pipenv so dependencies resolve correctly. Copy-paste invocations: CLI reference and README Usage.

Plain python may miss deps

Running python -m src outside the Pipenv shell can fail on imports like sentence-transformers. Use pipenv run or pipenv shell first.

Shell workflow

pipenv shell
python -m src "your query"

From the shell, run pytest and mkdocs serve per Testing and Publishing docs.

Exit the shell with exit or Ctrl+D.

Configuration for development

Task Approach
Persistent local overrides Edit .env (see Environment variables)
YAML experiments Add overlay files under config/ or set RA_CONFIG_DIR
Debug pipeline dumps RA_PIPELINE__DEBUG=true or RA_DEBUG=1 → logs/debug/
Fast iteration (heuristic) Default 3B Ollama or RA_SYNTHESIS__LLM_ENABLED=false
LLM integration testing Pin llama3.1:8b or use cloud keys — all unit tests mock LLM by default

Comment out RA_DEBUG=1 in .env.example unless you want debug JSON on every run.

Project layout (development)

Research_Assistant_Model/
├── src/                 # Application package (python -m src)
│   ├── __main__.py      # CLI entry
│   ├── api/             # Optional FastAPI layer
│   ├── config/          # Settings, LLM resolution
│   ├── core/            # Pipeline, registry, context
│   ├── research/        # Query expansion, ranking, clustering
│   ├── retrieval/       # Providers, retrieval stage
│   ├── analysis/        # Synthesis, gap analysis
│   └── reporting/       # Report generation, exports
├── tests/               # pytest suite
├── config/              # YAML defaults
├── setups/              # Ollama install, health check
├── docs/                # MkDocs source
└── logs/                # Runtime logs (gitignored)

Common development tasks

Task Command / link
Run all tests Testing
Skip slow subprocess tests Testing — Run tests
Single test file Testing — Run tests
Docs preview Publishing docs
Strict docs build Publishing docs
Health check Setup system
API server API overview

IDE / editor notes

  • Set the Python interpreter to the Pipenv virtualenv: pipenv --venv
  • Mark src/ as sources root if your IDE supports it
  • Tests import via from src.... — run pytest from repo root

Troubleshooting

Issue Fix
ModuleNotFoundError: sentence_transformers pipenv install inside project root
Ollama connection errors Setup system
Tests hang on subprocess Use pytest -m "not slow"
MkDocs strict warnings Fix broken nav links; run mkdocs build --strict locally