Eldermind Astro Engine API

Osiem systemów ezoterycznych. Jedno API. Gotowe dla AI.

REST pod /v1/* i serwer MCP pod /mcp — dwa interfejsy nad tym samym rdzeniem eldermind-core, w jednym procesie. Zero duplikacji logiki: cache, limit współbieżności, kredyty i obsługa błędów istnieją w jednym egzemplarzu.

Co liczy

Astrologia zachodnia · astrologia wedyjska (Jyotish) · Human Design · Gene Keys · Matryca Losu · BaZi (Cztery Filary) · numerologia pitagorejska · karta drakoniczna. Plus Animal Design dla psów, kotów i koni.

Wszystko lokalnie na Swiss Ephemeris. Żadnego zewnętrznego API astrologicznego w torze wykonania.

Related MCP server: Open Ephemeris

Trzy własności, na których stoi kontrakt

Determinizm. Każde obliczenie jest czystą funkcją swoich argumentów. Przypnij reference_date, a te same dane wejściowe zwrócą te same bajty bezterminowo. 29 testów złotych wywala build, jeśli ruszy się choć jedna liczba.

Poziomy szczegółowości. Pełny profil to ~30 KB, czyli ~7 700 tokenów — jedno wywołanie narzędzia zjadłoby kontekst modelu, zanim ten zdąży cokolwiek powiedzieć. detail: "summary" daje ~2 KB samych wniosków.

Częściowe powodzenie. W bundlu jeden system, który zawiedzie, nie kosztuje Cię pozostałych siedmiu — błąd ląduje w meta.errors[], reszta wraca normalnie. Urodzony w Tromsø dostaje 7 z 8 systemów zamiast błędu (Placidus jest za kołem podbiegunowym matematycznie nieokreślony).

Szybki start

Rdzeń jest osobnym repozytorium i nie ma go na PyPI, więc trzeba go sklonować obok i zainstalować pierwszy — w odwrotnej kolejności pip próbuje pobrać eldermind-core z sieci i przerywa instalację.

git clone https://github.com/ElderMindAI/eldermind-core.git
git clone https://github.com/ElderMindAI/eldermind-astro-api.git
cd eldermind-astro-api

python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ../eldermind-core
pip install -e ".[dev,mcp]"
cp .env.example .env.local
uvicorn app.main:app --port 8010 --reload

Wymagany Python 3.11+. Ekstras [mcp] nie jest opcjonalny w praktyce: bez niego serwis wstaje, odpowiada 200 na /health i ma komplet tras REST — ale nie ma /mcp, czyli tego, na czym stoi produkt.

Dokumentacja interaktywna: http://127.0.0.1:8010/docs

curl -X POST http://127.0.0.1:8010/v1/profile/complete \
  -H "Authorization: Bearer sk_test_development" \
  -H "Content-Type: application/json" \
  -d '{"subject":{"birth_date":"1993-09-01","birth_time":"14:30",
       "latitude":52.2297,"longitude":21.0122,"timezone":"Europe/Warsaw",
       "gender":"male"},"detail":"summary"}'

Podłączenie do Claude / Cursor / VS Code

// .cursor/mcp.json  ·  Claude Desktop: analogicznie
{
  "mcpServers": {
    "eldermind-astro": {
      "url": "https://api.eldermind.io/mcp",
      "headers": { "Authorization": "Bearer sk_live_TWOJ_KLUCZ" }
    }
  }
}

Lokalnie, przez stdio: python run_mcp_stdio.py.

Claude.ai / ChatGPT — bez kopiowania kluczy (OAuth 2.1)

Użytkownik podaje wyłącznie URL https://api.eldermind.io/mcp i przechodzi logowanie. Reszta jest odkrywana automatycznie:

Token OAuth to delegacja istniejącego konta, nie nowe konto. Ekran zgody prosi raz o klucz API; wydany token nosi jego identyfikator. Dzięki temu uprawnienia, kredyty i limity działają identycznie niezależnie od tego, czy żądanie przyszło z Bearer sk_live_..., czy z tokenu OAuth — reguły żyją w jednym miejscu.

Zakresy zawężają, nigdy nie poszerzają. Efektywny dostęp to część wspólna uprawnień planu i zakresów tokenu. Zgoda na system:bazi nie da dostępu do wedyjskiej, a plan obejmujący wszystko i tak nie przekroczy tego, na co użytkownik się zgodził. Katalog zakresów: GET /oauth/scopes.

Access token żyje godzinę, refresh 30 dni i rotuje przy każdym użyciu — skradziony działa tylko do najbliższego odświeżenia przez prawdziwego klienta. Kod autoryzacyjny jest jednorazowy. Odwołanie klucza natychmiast unieważnia wszystkie wydane na niego tokeny.

14 narzędzi

Bundle kosztuje 6 zamiast 9 — rabat jest narzędziem projektowym, nie promocją: steruje zachowaniem modelu ceną, żeby wybierał jedno wywołanie zamiast ośmiu.

Zasoby: eldermind://systems, eldermind://methodology Prompty: natal_reading, timing_advice, compatibility_brief

Dlaczego akurat tak

• resolve_birth_data jest osobnym narzędziem, bo model ma „Kraków", nigdy 52.23/21.01. Bez tego kroku każdy przepływ wykłada się na pierwszym pytaniu.

• Nazwy, nie kody. "Manifesting Generator", nie "type_2". Model ma to rozumieć bez tablicy odwzorowań.

• Błędy niosą instrukcję. Komunikat przy wyczerpanych kredytach mówi wprost: „poinformuj użytkownika i wskaż stronę cennika — nie wymyślaj wyniku". Model, który dostanie sam kod błędu, dopowie sobie kartę.

• Ostrzeżenia zamiast fałszywej precyzji. Brak godziny urodzenia naprawdę psuje Ascendent, domy i Księżyc — warnings mówi to modelowi wprost.

Kontrakt błędów

Każda awaria wygląda tak samo:

{"error": {
  "code": "AMBIGUOUS_LOCAL_TIME",
  "message": "Local time 02:30:00 on 1993-03-28 does not exist in Europe/Warsaw (daylight-saving gap).",
  "field": "birth_time",
  "request_id": "req_01JD8X...",
  "docs_url": "https://eldermind.io/api/docs/errors#ambiguous-local-time"
}}

INVALID_API_KEY · INSUFFICIENT_CREDITS · SYSTEM_NOT_ENTITLED · INVALID_TIMEZONE · AMBIGUOUS_LOCAL_TIME · DATE_OUT_OF_RANGE · HOUSE_SYSTEM_UNAVAILABLE · GEOCODING_FAILED · RATE_LIMITED · SERVICE_BUSY · CALCULATION_ERROR

Ograniczenia — świadome i udokumentowane

• Bez godziny urodzenia przyjmujemy 12:00; Ascendent, domy, filar godziny i Księżyc są niewiarygodne. Zawsze oflagowane w warnings.

• Za kołem podbiegunowym Placidus jest nieokreślony. Karta zachodnia zwraca typowany błąd z podpowiedzią; wedyjska liczy się dalej (Whole Sign działa wszędzie).

• Przejścia czasu letniego — godzina z luki wiosennej nigdy nie istniała, z nakładki jesiennej wystąpiła dwa razy. Odrzucamy obie zamiast zgadywać.

• Zakres dat 1800–2200.

Bezpieczeństwo i RODO

Klucze: HMAC-SHA256 z pepperem, plaintext nigdy nie trafia do bazy — przechowujemy hash i krótki prefiks (sk_live_a1b2…), po którym użytkownik rozpoznaje własne klucze w panelu. Pepper żyje w środowisku, nie w bazie, więc sam wyciek bazy nie wystarczy do podrobienia klucza — i, co ciekawsze, nie wystarczy też zapis do bazy. Hashe sprzed tej zmiany zaczynają się od $argon2id$ i są nadal akceptowane przy weryfikacji.

Klucz cache'u to SHA-256 wejść — nie da się z niego odtworzyć daty urodzenia. usage_events zawiera wyłącznie metryki; data urodzenia i imię nigdy nie trafiają do zapisu ani do logów. Test tego pilnuje.

Testy

pytest                        # 281 testów
pytest ../eldermind-core      # 122 testy, w tym 29 złotych

Licencja

Kod jest udostępniony do wglądu, nie open source. Wolno go czytać, studiować i oceniać; użycie w produkcie lub usłudze wymaga pisemnej zgody. Pełne warunki: LICENSE.