atlas-world-intel 1.0.0__tar.gz

atlas_world_intel-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Khizar Arain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atlas_world_intel-1.0.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: atlas-world-intel
+Version: 1.0.0
+Summary: World Intelligence CLI - explore countries, economies, currencies and geography from your terminal
+Author-email: Khizar Arain <your@email.com>
+License-Expression: MIT
+Project-URL: Homepage, https://khizar-arain.vercel.app
+Project-URL: Repository, https://github.com/khizerarain/atlas
+Keywords: cli,world,geography,countries,terminal,atlas
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: thefuzz>=0.22.0
+Requires-Dist: pytz>=2024.1
+Requires-Dist: pycountry>=23.12.11
+Requires-Dist: geopy>=2.4.0
+Requires-Dist: forex-python>=1.8
+Dynamic: license-file
+
+# ATLAS
+
+## Installation
+
+```bash
+pip install atlas-world-intel
+```
+
+Then run:
+
+```bash
+atlas
+```
+
+No cloning required.
+
+ATLAS is a Python command-line experience for exploring the world from your terminal. It combines country data, rankings, currency conversion, travel tips, a geography quiz, and AI-powered explanations into a single polished dashboard.
+
+![ATLAS demo](demo.gif)
+
+> Animated demo placeholder — add a GIF named demo.gif to this folder to replace the placeholder.
+
+## Development
+
+```bash
+git clone https://github.com/khizerarain/atlas
+cd atlas
+pip install -r requirements.txt
+cp .env.example .env
+# Add your API keys to .env
+python -m atlas.main
+```
+
+## Commands
+
+| Command | Example | Description |
+| --- | --- | --- |
+| atlas country | atlas country japan | Show a Rich country profile with key facts |
+| atlas compare | atlas compare france germany | Compare two countries side by side |
+| atlas top | atlas top population | Show the top 10 countries by population, area, or borders |
+| atlas convert | atlas convert 100 USD PKR | Convert currencies using live exchange rates |
+| atlas time | atlas time japan | Show the current local time for a country |
+| atlas quiz | atlas quiz | Run a 10-question geography quiz |
+| atlas learn | atlas learn africa | Show continent-level highlights |
+| atlas ask | atlas ask What is the capital of Morocco? | Ask ATLAS AI a geography question |
+| atlas travel | atlas travel japan | Show travel tips and emergency info |
+
+## Tech Stack
+
+- Python
+- Typer
+- Rich
+- RestCountries API
+- OpenAI
+- exchangerate.host
+
+## Environment Variables
+
+- OPENAI_API_KEY: Required for AI answers via the atlas ask command.
+- EXCHANGE_API_KEY: Optional for exchange-rate integrations; the default free endpoint is used when it is not present.
+
+## License
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)

atlas_world_intel-1.0.0/README.md

@@ -0,0 +1,64 @@
+# ATLAS
+
+## Installation
+
+```bash
+pip install atlas-world-intel
+```
+
+Then run:
+
+```bash
+atlas
+```
+
+No cloning required.
+
+ATLAS is a Python command-line experience for exploring the world from your terminal. It combines country data, rankings, currency conversion, travel tips, a geography quiz, and AI-powered explanations into a single polished dashboard.
+
+![ATLAS demo](demo.gif)
+
+> Animated demo placeholder — add a GIF named demo.gif to this folder to replace the placeholder.
+
+## Development
+
+```bash
+git clone https://github.com/khizerarain/atlas
+cd atlas
+pip install -r requirements.txt
+cp .env.example .env
+# Add your API keys to .env
+python -m atlas.main
+```
+
+## Commands
+
+| Command | Example | Description |
+| --- | --- | --- |
+| atlas country | atlas country japan | Show a Rich country profile with key facts |
+| atlas compare | atlas compare france germany | Compare two countries side by side |
+| atlas top | atlas top population | Show the top 10 countries by population, area, or borders |
+| atlas convert | atlas convert 100 USD PKR | Convert currencies using live exchange rates |
+| atlas time | atlas time japan | Show the current local time for a country |
+| atlas quiz | atlas quiz | Run a 10-question geography quiz |
+| atlas learn | atlas learn africa | Show continent-level highlights |
+| atlas ask | atlas ask What is the capital of Morocco? | Ask ATLAS AI a geography question |
+| atlas travel | atlas travel japan | Show travel tips and emergency info |
+
+## Tech Stack
+
+- Python
+- Typer
+- Rich
+- RestCountries API
+- OpenAI
+- exchangerate.host
+
+## Environment Variables
+
+- OPENAI_API_KEY: Required for AI answers via the atlas ask command.
+- EXCHANGE_API_KEY: Optional for exchange-rate integrations; the default free endpoint is used when it is not present.
+
+## License
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)

atlas_world_intel-1.0.0/atlas/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

atlas_world_intel-1.0.0/atlas/commands/__init__.py

@@ -0,0 +1 @@
+# commands package

atlas_world_intel-1.0.0/atlas/commands/ask.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import os
+
+import typer
+
+from atlas.core.api import ask_ai, check_internet
+from atlas.core.display import show_ai_answer, show_error, show_no_internet, show_warning
+
+app = typer.Typer(help="Ask ATLAS AI")
+
+
+@app.callback(invoke_without_command=True)
+def ask_ai_command(question: str = typer.Argument(..., help="Question to ask ATLAS")) -> None:
+    if not question:
+        show_error("Please provide a question.")
+        raise typer.Exit(code=1)
+
+    if not os.getenv("OPENAI_API_KEY") or os.getenv("OPENAI_API_KEY") == "your_key_here":
+        show_warning("OpenAI API key is not configured. Add it to .env to enable AI answers.")
+        return
+
+    if not check_internet():
+        show_no_internet()
+        return
+
+    answer = ask_ai(question)
+    if answer:
+        show_ai_answer(answer)
+    else:
+        show_error("ATLAS AI could not answer that question right now.")

atlas_world_intel-1.0.0/atlas/commands/compare.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import typer
+
+from atlas.core.api import check_internet, get_country
+from atlas.core.display import show_comparison_table, show_error, show_no_internet
+
+app = typer.Typer(help="Compare two countries")
+
+
+@app.callback(invoke_without_command=True)
+def compare_countries(
+    country_a: str = typer.Argument(..., help="First country"),
+    country_b: str = typer.Argument(..., help="Second country"),
+) -> None:
+    if not country_a or not country_b:
+        show_error("Please provide two country names.")
+        raise typer.Exit(code=1)
+
+    if not check_internet():
+        show_no_internet()
+        return
+
+    a = get_country(country_a)
+    b = get_country(country_b)
+    if not a or not b:
+        show_error("One or both countries could not be found.")
+        return
+
+    show_comparison_table(a, b)

atlas_world_intel-1.0.0/atlas/commands/country.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import typer
+from rich.prompt import Prompt
+
+from atlas.core.api import check_internet, get_country, search_countries
+from atlas.core.display import show_country_card, show_error, show_loading, show_no_internet, show_suggestions
+
+app = typer.Typer(help="Look up country details")
+
+
+@app.callback(invoke_without_command=True)
+def country_lookup(name: str = typer.Argument(..., help="Country name")) -> None:
+    if not name:
+        show_error("Please provide a country name.")
+        raise typer.Exit(code=1)
+
+    if not check_internet():
+        show_no_internet()
+        return
+
+    with show_loading(f"Looking up {name}..."):
+        data = get_country(name)
+
+    if not data:
+        suggestions = [c["name"] for c in search_countries(name, limit=3)]
+        show_suggestions(name, suggestions)
+        return
+
+    show_country_card(data)
+
+
+@app.command("clock")
+def show_world_clock_command(country_name: str) -> None:
+    if not check_internet():
+        show_no_internet()
+        return
+
+    data = get_country(country_name)
+    if not data:
+        show_error(f"Country '{country_name}' was not found.")
+        return
+
+    from datetime import datetime
+    from zoneinfo import ZoneInfo
+
+    tz_name = None
+    for candidate in data.get("timezones") or []:
+        try:
+            tz_name = candidate
+            ZoneInfo(candidate)
+            break
+        except Exception:
+            continue
+
+    if not tz_name:
+        show_error("No timezone data available for that country.")
+        return
+
+    now = datetime.now(ZoneInfo(tz_name))
+    offset = now.strftime("%z")
+    offset_text = f"UTC{offset[:3]}:{offset[3:]}"
+    from atlas.core.display import show_world_clock
+
+    show_world_clock(f"{data.get('capital', 'N/A')}, {data.get('name', 'N/A')}", now.strftime("%Y-%m-%d %H:%M:%S"), offset_text)

atlas_world_intel-1.0.0/atlas/commands/currency.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import typer
+
+from atlas.core.api import check_internet, convert_currency
+from atlas.core.display import show_conversion, show_error, show_no_internet
+
+app = typer.Typer(help="Convert currencies")
+
+
+@app.callback(invoke_without_command=True)
+def convert_currency_command(
+    amount: float = typer.Argument(..., help="Amount to convert"),
+    from_code: str = typer.Argument(..., help="Source currency code"),
+    to_code: str = typer.Argument(..., help="Destination currency code"),
+) -> None:
+    if amount <= 0:
+        show_error("Amount must be greater than zero.")
+        raise typer.Exit(code=1)
+
+    if not check_internet():
+        show_no_internet()
+        return
+
+    result = convert_currency(amount, from_code, to_code)
+    if not result:
+        show_error(
+            f"Unable to convert {from_code} to {to_code}. Try valid codes such as USD, EUR, GBP, JPY, PKR."
+        )
+        return
+
+    show_conversion(
+        result["amount"],
+        result["from"],
+        result["to"],
+        result["result"],
+        rate=result.get("rate"),
+        date=result.get("date"),
+    )

atlas_world_intel-1.0.0/atlas/commands/learn.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import typer
+
+from atlas.core.api import check_internet, get_all_countries
+from atlas.core.display import show_error, show_learn_panel, show_no_internet
+
+app = typer.Typer(help="Learn continent summaries")
+
+VALID_CONTINENTS = {
+    "africa": "Africa",
+    "asia": "Asia",
+    "europe": "Europe",
+    "americas": "Americas",
+    "oceania": "Oceania",
+}
+
+
+@app.callback(invoke_without_command=True)
+def show_continent_summary(continent: str = typer.Argument(..., help="Continent name")) -> None:
+    normalized = continent.strip().lower()
+    if normalized not in VALID_CONTINENTS:
+        show_error("Continent must be one of: Africa, Asia, Europe, Americas, Oceania")
+        raise typer.Exit(code=1)
+
+    if not check_internet():
+        show_no_internet()
+        return
+
+    countries = [c for c in get_all_countries() if c.get("continent", "").lower() == VALID_CONTINENTS[normalized].lower()]
+    if not countries:
+        show_error("No country data available for that continent.")
+        return
+
+    largest = max(countries, key=lambda c: c.get("area_km2") or 0)
+    most_populous = max(countries, key=lambda c: c.get("population") or 0)
+    show_learn_panel(VALID_CONTINENTS[normalized], len(countries), largest, most_populous)

atlas_world_intel-1.0.0/atlas/commands/quiz.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import json
+import random
+from pathlib import Path
+
+import typer
+from rich.table import Table
+
+from atlas.core.display import show_error, show_loading, show_success
+
+app = typer.Typer(help="Take a geography quiz")
+
+
+def _load_questions() -> list[dict]:
+    data_path = Path(__file__).resolve().parent.parent / "data" / "quiz_questions.json"
+    with data_path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+@app.callback(invoke_without_command=True)
+def run_quiz() -> None:
+    questions = _load_questions()
+    if len(questions) < 10:
+        show_error("Not enough quiz questions available.")
+        return
+
+    random.shuffle(questions)
+    selected = questions[:10]
+    score = 0
+    results = []
+
+    for idx, item in enumerate(selected, start=1):
+        with show_loading(f"Question {idx}/10"):
+            pass
+        answer = typer.prompt(f"{idx}. {item['question']}")
+        if str(answer).strip().lower() == str(item["answer"]).strip().lower():
+            score += 1
+            results.append((item["question"], answer, item["answer"], "✓"))
+        else:
+            results.append((item["question"], answer, item["answer"], "✗"))
+
+    if score == 10:
+        rating = "🌍 World Expert"
+    elif score >= 7:
+        rating = "✈️ Seasoned Traveler"
+    elif score >= 4:
+        rating = "🗺️ Explorer"
+    else:
+        rating = "📚 Keep Studying"
+
+    table = Table(title=f"Quiz Score: {score}/10 — {rating}", border_style="cyan", header_style="bold cyan")
+    table.add_column("#", justify="right")
+    table.add_column("Question")
+    table.add_column("Your Answer")
+    table.add_column("Correct Answer")
+    table.add_column("Result")
+    for i, (question, your_answer, correct_answer, result) in enumerate(results, start=1):
+        table.add_row(str(i), question, your_answer, correct_answer, result)
+
+    from rich.console import Console
+
+    Console().print(table)
+    show_success(f"You scored {score}/10 — {rating}")

atlas_world_intel-1.0.0/atlas/commands/rankings.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import typer
+
+from atlas.core.api import check_internet, get_all_countries
+from atlas.core.display import show_error, show_no_internet, show_rankings_table
+
+app = typer.Typer(help="Show top rankings")
+
+
+@app.callback(invoke_without_command=True)
+def show_rankings(metric: str = typer.Argument("population", help="Metric to rank by")) -> None:
+    if metric not in {"population", "area", "borders"}:
+        show_error("Metric must be one of: population, area, borders")
+        raise typer.Exit(code=1)
+
+    if not check_internet():
+        show_no_internet()
+        return
+
+    countries = get_all_countries()
+    if not countries:
+        show_error("No country data available right now.")
+        return
+
+    if metric == "population":
+        ranked = sorted(countries, key=lambda c: (c.get("population") or 0), reverse=True)[:10]
+        rows = [(i + 1, c.get("flag_emoji", ""), c.get("name", "N/A"), f"{int(c.get('population') or 0):,}") for i, c in enumerate(ranked)]
+        title = "🌍 Top 10 by Population"
+    elif metric == "area":
+        ranked = sorted(countries, key=lambda c: (c.get("area_km2") or 0), reverse=True)[:10]
+        rows = [(i + 1, c.get("flag_emoji", ""), c.get("name", "N/A"), f"{int(c.get('area_km2') or 0):,} km²") for i, c in enumerate(ranked)]
+        title = "🌍 Top 10 by Area"
+    else:
+        ranked = sorted(countries, key=lambda c: len(c.get("borders") or []), reverse=True)[:10]
+        rows = [(i + 1, c.get("flag_emoji", ""), c.get("name", "N/A"), str(len(c.get("borders") or []))) for i, c in enumerate(ranked)]
+        title = "🌍 Top 10 by Borders"
+
+    show_rankings_table(title, rows)

atlas_world_intel-1.0.0/atlas/commands/travel.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from atlas.core.display import show_error
+
+app = typer.Typer(help="Travel tips and info")
+
+
+@app.callback(invoke_without_command=True)
+def travel_info(country: str = typer.Argument(..., help="Country name")) -> None:
+    if not country:
+        show_error("Please provide a country name.")
+        raise typer.Exit(code=1)
+
+    data_path = Path(__file__).resolve().parent.parent / "data" / "travel_info.json"
+    with data_path.open("r", encoding="utf-8") as handle:
+        content = json.load(handle)
+
+    match = content.get(country.lower())
+    if not match:
+        show_error("Travel info is not available for that country yet.")
+        return
+
+    from rich.console import Console
+    from rich.panel import Panel
+
+    lines = [f"Visa: {match.get('visa', 'N/A')}", f"Emergency: {match.get('emergency_numbers', 'N/A')}", f"Best months: {match.get('best_months', 'N/A')}", f"Weather: {match.get('weather_overview', 'N/A')}"]
+    Console().print(Panel("\n".join(lines), title=f"✈️ Travel tips for {country.title()}", border_style="cyan"))

atlas_world_intel-1.0.0/atlas/core/__init__.py

@@ -0,0 +1 @@
+# core package