Astrospect

Astrospect is a Django web application for calculating and exploring birth charts. It pairs transparent chart calculations with plain-language, source-grounded explanations generated by a configurable language model.

What the app does

• Calculates tropical-zodiac placements and whole-sign houses.
• Displays the seven classical planets and the True Node, along with the four chart angles when birth time and birthplace are available.
• Lets users expand a placement for a short explanation or ask follow-up questions about their chart.
• Uses a small, approved Jyotisha source catalog for the AI guide; model output can cite only sources in that catalog.
• Supports optional saved charts and caches generated placement summaries.

Astrospect deliberately presents its use of traditional Jyotisha as a modern adaptation. The chart uses the tropical zodiac and whole-sign houses; it does not calculate sidereal placements, nakshatras, or dashas. Traditional Jyotisha texts do not establish that their authors prescribed tropical astrology, and the app labels this distinction rather than implying otherwise. Interpretive text is framed as historical symbolism, not scientific prediction.

Design choices

PostgreSQL for application data

The project started with SQLite while the application was being developed. PostgreSQL is now the configured database because it is a better fit for a hosted, multi-user Django application:

• It is a client-server database that can be shared by multiple web workers, rather than a single local database file.
• It provides durable, managed database options for deployment and avoids making production data depend on the web service's local filesystem.
• It gives local development and production the same database behavior, reducing surprises when deploying.
• It supports the app's Django models and JSON-backed chart and summary data.

The application does not silently fall back to SQLite. Configure PostgreSQL with DATABASE_URL, or provide the individual DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, and DB_PORT settings. DATABASE_URL takes precedence when both forms are present. Django migrations create or update the schema; they do not automatically copy existing records from an old SQLite database into PostgreSQL.

OpenAI-compatible API for model flexibility

The application uses the OpenAI Python SDK's Chat Completions interface, but that does not mean it is locked to OpenAI-hosted models. The SDK supports an OpenAI-compatible API endpoint, so astrospect selects its provider, model, and credential through environment variables rather than hard-coding a provider into chart or chat code.

The current configuration uses OpenRouter and the free model nvidia/nemotron-3.5-lightning:free. To try another model or compatible provider, change AI_BASE_URL, AI_API_KEY, and AI_MODEL; the application code can stay the same as long as the provider supports the Chat Completions API used here. Model availability, free-tier limits, output quality, and provider-specific behavior can change, so check the provider's current model listing before switching.

The selected model is asked to follow server-controlled instructions and return a structured answer. The app validates its response and resolves source citations against the approved catalog instead of trusting model-generated source URLs.

Running locally

Requirements

• Python and pip
• A PostgreSQL server and a database/user for astrospect
• An OpenRouter API key and a model that supports the compatible API, if you want live AI responses
• A Geoapify API key, if users should be able to look up birthplaces

Install and configure

From the project directory, create and activate a virtual environment, then install dependencies:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Create a .env file in the project root. For example:

# PostgreSQL connection. Use either DATABASE_URL or the DB_* values below.
DATABASE_URL=postgresql://astrospect:your-password@localhost:5432/astrospect

# OpenRouter's OpenAI-compatible API
AI_API_KEY=your_openrouter_api_key
AI_BASE_URL=https://openrouter.ai/api/v1
AI_MODEL=nvidia/nemotron-3.5-lightning:free
AI_TIMEOUT_SECONDS=60

# Optional: Geoapify birthplace lookup
GEOAPIFY_API_KEY=your_geoapify_api_key

# Local Django settings
DJANGO_DEBUG=True
DJANGO_SECRET_KEY=replace-this-for-local-development
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1

Keep .env private; it is excluded from Git. Never put API keys or production secrets in source files or commit them to the repository.

If you prefer separate PostgreSQL connection settings, omit DATABASE_URL and set all of the following instead:

DB_NAME=astrospect
DB_USER=astrospect
DB_PASSWORD=your-password
DB_HOST=localhost
DB_PORT=5432

The .env file is optional for Django itself, but AI and geocoding features need their corresponding provider settings. Without an AI key or model, live inference is not available.

Apply database migrations and start the development server:

python manage.py migrate
python manage.py runserver

Open http://127.0.0.1:8000/ in a browser. Django's default development server is for local development, not production hosting.

This is the beginning of the README. Read the rest at the original. Read the full README ↗