Skip to content

Quick Start

Get ASHAI up and running in minutes with this step-by-step guide.

Prerequisites

  • Python 3.10 or higher (required for modern type syntax)
  • OpenAI API key
  • (Optional) Google Cloud account for Healthcare NLP

Installation

1. Clone and Setup

git clone https://github.com/your-org/ashai
cd ashai

# Create and activate a project-root virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Environment Configuration

Copy the example environment file and edit as needed:

cp .env.example .env
# then open .env and fill in required keys

3. Start the Server

Use the provided run script (recommended):

./run.sh

This script will: - Stop any existing server on port 8000 - Load environment variables from .env file
- Start the server at http://localhost:8000 with auto-reload

Note: Ensure your virtual environment is activated (source venv/bin/activate) before running the script.

Alternative manual start: 

uvicorn main:app --reload

4. Verify Installation

Check that the server is running:

curl http://localhost:8000/health
# Should return: {"status":"healthy","service":"ASHAI"}

Visit the web interface at http://localhost:8000

First API Call

Test the main ASHAI agent:

curl -X POST http://localhost:8000/agent/ashai \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What are the symptoms of diabetes?"}
    ],
    "profile": "Adult patient, no known conditions"
  }'

import requests

response = requests.post('http://localhost:8000/agent/ashai', json={
    "messages": [
        {"role": "user", "content": "What are the symptoms of diabetes?"}
    ],
    "profile": "Adult patient, no known conditions"
})

result = response.json()
print(f"Response: {result['response']}")
print(f"Sources: {len(result['searches'])} search(es) performed")

const response = await fetch('http://localhost:8000/agent/ashai', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    messages: [
      { role: 'user', content: 'What are the symptoms of diabetes?' }
    ],
    profile: 'Adult patient, no known conditions'
  })
});

const result = await response.json();
console.log('Response:', result.response);
console.log('Sources:', result.searches.length, 'search(es) performed');

Example Queries

Try these example queries to see ASHAI's intelligent routing in action:

{
  "messages": [
    {"role": "user", "content": "I am pregnant"},
    {"role": "user", "content": "Can I eat fish during pregnancy?"}
  ],
  "profile": "Name: Sarah\nAge: 28\nPregnant: Yes"
}
Routes to: Googlesheet FAQ + PubMed

General Medical Query

{
  "messages": [
    {"role": "user", "content": "What are the symptoms of high blood pressure?"}
  ],
  "profile": "Adult patient seeking information"
}
Routes to: September Health Library + PubMed

Complex Medical Query

{
  "messages": [
    {"role": "user", "content": "I'm taking metformin for diabetes and lisinopril for blood pressure. Are there any interactions?"}
  ],
  "profile": "Patient with diabetes and hypertension"
}
Routes to: PubMed + September Health Library

Available Endpoints

Endpoint Purpose Best For
/agent/ashai Main AI agent with intelligent routing General medical queries
/agent/september September Health Library only Structured medical content
/search/pubmed PubMed search Research-based answers
/search/googlesheet Googlesheet FAQ search Pregnancy/maternal health

Troubleshooting

Server Won't Start

# Check if port 8000 is in use
lsof -i :8000

# Kill existing process
pkill -f "uvicorn main:app"

# Try starting again
./run.sh

September Health Database Issues

If you see warnings about September search returning 0 results or ChromaDB being empty:

# Check ChromaDB health
cd search/september
python check_chroma_health.py --verbose

# If database is empty, rebuild from cached files
python september_scraper.py --scrape-all
python section_processor.py --input data/september_articles.json --output data/september_sections.json
cd ../..  # Go back to project root
python search/september/init_september.py --force-rebuild

# Verify it's working
cd search/september
python check_chroma_health.py --verbose

See the Voice Interfaces page for voice interaction options.

API Key Issues

# Check if environment variable is set
echo $OPENAI_API_KEY

# Verify .env file exists and has correct format
cat .env

Import Errors

# Ensure virtual environment is activated
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Next Steps

Performance Notes

  • First Request may take 3-5 seconds due to model loading
  • Subsequent Requests typically respond in 1-3 seconds
  • Caching improves performance for repeated queries
  • Logs are available in ashai_performance.log for debugging