npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

acta-socratica

v0.2.1

Published

Terminal-based Socratic Academic Advisor & Autonomous Research Agent for Universities and Scholars

Readme

Acta Socratica AI 🏛️

Socratic Academic Advisor & Autonomous Research Agent CLI
Built for Academic Integrity, Multi-Model Research, and Local Data Protection.


English

🌟 Overview

Acta Socratica is a terminal-based AI research advisor for students, researchers, and scholars working on theses, papers, and academic projects. Instead of writing academic work on your behalf, it uses the Socratic method to ask critical questions and help you develop your own research and synthesis.

⚡ Features

1. Local document processing and privacy

  • PDF (.pdf), Word (.docx), LaTeX (.tex), and code files are processed locally before any content is sent to an AI provider.
  • Converts supported documents into clean, structured Markdown.
  • Helps reduce token usage compared with sending raw document content.
  • Can redact personal information such as names, email addresses, Turkish ID numbers, and phone numbers before AI requests.

2. Multiple AI providers — bring your own key

Choose from supported providers, including:

  • Google Gemini: gemini-2.5-flash (default), gemini-2.5-pro
  • Anthropic Claude: claude-sonnet-4-6
  • OpenAI: gpt-5 (default), gpt-4.1
  • DeepSeek: deepseek-chat
  • Alibaba Qwen: qwen-plus
  • Local models (Ollama): offline operation, for example deepseek-r1:latest
  • OpenRouter / Groq: access to open-source models through unified services

Model IDs are passed directly to the selected provider. You can use any model ID supported by that provider with /model <provider> <model-id> or the config --provider <provider> --model <model-id> command; Acta Socratica does not maintain a model whitelist.

3. Socratic advisor and academic reviewer

  • Focuses on conceptual, methodological, and structural guidance instead of generating full academic text.
  • Points out inconsistencies, reasoning gaps, and methodology issues in a direct and respectful way.
  • Shows response time and provider-reported token usage after each answer; the same metrics are included in JSON and Markdown exports.
  • Wraps terminal responses at word boundaries to keep long output readable without adding hyphens.

🚀 Installation and startup

Requirements

  • Node.js 18+ (Node.js 24 recommended)

Install from npm

npm install -g acta-socratica
acta

For global npm installations, Acta Socratica checks for a newer version when an interactive session starts. If one is available, it asks before updating. Accepting runs the npm upgrade and exits; restart Acta Socratica to use the new version. This check is not run from source or from the .exe.

Run from the project directory

# Windows launcher
.\acta.cmd

# Build/update the Windows executable with the latest source changes
npm run build:exe

# Run the executable
.\Acta Socratica.exe

# Or run with npm
npm start

# Development mode
npm run dev

🛠️ Usage

Interactive terminal session

acta

Available slash commands:

  • /menu: Redisplay the session start screen (model, loaded document, privacy status, and basic commands) without clearing conversation history or the loaded document.
  • /file <path>: Convert a PDF or DOCX locally to Markdown and load it into the session (for example, /file "./thesis draft.docx").
  • /doc: Show the active document's word count, estimated tokens, and status.
  • /model <provider> [model]: Change the active model (for example, /model deepseek deepseek-reasoner).
  • /key <provider> <key>: Save an API key securely (for example, /key gemini YOUR_API_KEY).
  • /lang <code>: Change the advisory language (tr, en, de, fr, or es).
  • /privacy: Toggle personal-information redaction.
  • /clear: Clear the conversation history while keeping the loaded document.
  • /export [path]: Export the conversation as JSON, or as Markdown when the path ends in .md.
  • /update: Check the latest npm version and, after confirmation, update a global npm installation. Source-code and other non-global installations are not updated automatically.
  • /critique: Get a rigorous peer-review critique of logic, evidence, and methodology.
  • /methodology: Compare research methods and examine variables, controls, confounders, and risks through guiding questions.
  • /stats-help: Work through suitable statistical tests and assumption checks based on the study design and data.
  • /literature-review: Thematically map supplied literature into consensus, debates, and research gaps without inventing sources.
  • /thesis-plan: Build a deadline-driven chapter roadmap with weekly targets and three actions for this week.
  • /next-steps: Identify the next phase and three concrete actions for this week.
  • /outline: Create a heading outline with word targets.
  • /slide-outline: Structure the work as a 10-slide presentation plan.
  • /fact-check: Assess claims by evidence strength and flag verification needs.
  • /citation: Check citation-style consistency and missing bibliographic details.
  • /latex-help: Explain the likely root cause of a LaTeX error and how to address it.
  • /revise-guide: Receive line-by-line conceptual revision notes without directly rewriting text.
  • /help: Show the bilingual command help.
  • /exit: Exit the program.

Academic commands follow the integrity guidance in SKILL.md: they provide critical, Socratic feedback rather than ready-to-submit academic text. /revise-guide never rewrites or paraphrases submitted text.

To try the commands in the Windows executable, run npm run build:exe after changing the source, then launch .\Acta Socratica.exe and enter /help or /menu. For example, try /critique Evaluate my research question: ... or /slide-outline Create a presentation plan for .... Academic commands need a configured AI provider/API key and network access. /update checks npm, but a packaged .exe is not a global npm installation and will not replace itself; rebuild the executable after updating the source.

In Windows CMD, right-click to paste; in Windows Terminal, use Ctrl+Shift+V. Quote file paths containing spaces.

Review a document on startup

acta chat ./thesis.docx

Convert a document locally

Convert a PDF or Word document to Markdown without sending it to an AI provider:

acta convert ./paper.pdf ./paper_clean.md

Configure API keys

Keys can be saved from the terminal:

.\acta.cmd config --gemini "YOUR_GEMINI_API_KEY"
.\acta.cmd config --anthropic "YOUR_ANTHROPIC_API_KEY"
.\acta.cmd config --deepseek "YOUR_DEEPSEEK_API_KEY"
.\acta.cmd config --openai "YOUR_OPENAI_API_KEY"
.\acta.cmd config --qwen "YOUR_QWEN_API_KEY"

# Choose a default provider and model
.\acta.cmd config --provider deepseek --model deepseek-reasoner

Or use a .env file:

GEMINI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
DEEPSEEK_API_KEY=your_key_here
DASHSCOPE_API_KEY=your_key_here

🔒 Security and data handling

  1. Local document parsing: Word and PDF files are parsed by the local Node.js process, not by a third-party document conversion service.
  2. Personal-information redaction: Email addresses, Turkish ID numbers, phone numbers, and API-key patterns can be redacted before content is sent to an AI provider.
  3. Local settings: API keys are stored in the user's local profile and are not sent to this project's servers.
  4. Local session export: /export saves conversation history to a local JSON or Markdown file.

📜 License

This project is released under the MIT License.

💬 Feedback and Contact

We welcome your feedback, suggestions, and comments:


Türkçe

🌟 Overview / Genel Bakış

Acta Socratica, araştırmacıların, lisans ve lisansüstü öğrencilerin tez, makale ve bilimsel projelerini geliştirmeleri için tasarlanmış terminal tabanlı bir yapay zeka asistanıdır (CLI Agent).

Geleneksel AI araçları kullanıcının yerine doğrudan metin yazarak Turnitin / iThenticate gibi sistemlerde yüksek AI ve intihal tespit oranlarına yol açarken; Acta Socratica, kullanıcının yerine yazmayı reddeder ve Sokratik Yöntemle (Socratic Method) eleştirel sorular sorarak araştırmacının kendi bilimsel sentezini yapmasını sağlar.


⚡ Temel Yetenekler & Mimari

1. 🛡️ Sıfır Veri Sızıntısı & Yerel Markdown Dönüştürme Motoru

  • PDF (.pdf), Word (.docx), LaTeX (.tex) veya kod dosyalarınızı harici bir buluta göndermeden önce tamamen yerel makinenizde işler.
  • Dosyaları temiz, yapılandırılmış Markdown formatına dönüştürür.
  • Token Tasarrufu: Ham binary dosyalara kıyasla %50-%70 token tasarrufu sağlar.
  • Gizlilik Kalkanı (PII Redaction): İsimler, e-posta adresleri, TC kimlik ve telefon numaraları API'ye gitmeden önce yerel ortamda filtrelenir.

2. 🤖 Çoklu AI Model Desteği (Bring Your Own Key)

Tek bir arayüzden dünyanın en gelişmiş modelleri arasında geçiş yapın:

  • Google Gemini: gemini-2.5-flash (Varsayılan), gemini-2.5-pro
  • Anthropic Claude: claude-sonnet-4-6
  • OpenAI: gpt-5 (varsayılan), gpt-4.1
  • DeepSeek: deepseek-chat
  • Alibaba Qwen: qwen-plus
  • Yerel Modeller (Ollama): Tamamen internetsiz / çevrimdışı çalışma (örn: deepseek-r1:latest)
  • OpenRouter / Groq: Açık kaynak modeller için birleşik erişim

Model kimlikleri doğrudan seçilen sağlayıcıya iletilir. /model <sağlayıcı> <model-id> veya config --provider <sağlayıcı> --model <model-id> komutuyla sağlayıcının desteklediği herhangi bir modeli kullanabilirsiniz; Acta Socratica model beyaz listesi uygulamaz.

3. 🎓 Sokratik Danışman & Akademik Hakem (Peer Reviewer)

  • Turnitin Koruması: Doğrudan tam metin üretmez; kavramsal, metodolojik ve yapısal rehberlik sunar.
  • Eleştirel Hakem Gözü: Argüman tutarsızlıklarını, mantık hatalarını ve metodoloji açıklarını yapay övgülerden uzak, dürüst ve saygılı biçimde işaret eder.
  • Her yanıtın ardından geçen süreyi ve sağlayıcının bildirdiği token kullanımını gösterir; bu metrikler JSON ve Markdown dışa aktarımlarına da eklenir.
  • Uzun terminal yanıtlarını tire eklemeden kelime sınırlarında sararak okunabilirliği korur.

🚀 Kurulum ve Çalıştırma

Gereksinimler

  • Node.js 18+ (Node.js v24 önerilir)

Başlatma

Proje dizininde terminali açıp şu komutlardan birini çalıştırabilirsiniz:

# npm ile global kurulum:
npm install -g acta-socratica
acta

# Doğrudan çalıştırma:
.\acta.cmd

# Güncel kaynak kodla Windows uygulamasını oluşturma/güncelleme:
npm run build:exe

# Uygulamayı çalıştırma:
.\Acta Socratica.exe

# Veya npm ile:
npm start

# Geliştirme modu:
npm run dev

Global npm kurulumunda Acta Socratica, interaktif oturum başlarken yeni sürüm olup olmadığını kontrol eder. Güncelleme varsa onayınızı ister; kabul ederseniz npm üzerinden günceller ve yeniden başlatmanızı bekler. Kaynak koddan veya .exe dosyasından çalıştırıldığında bu kontrol yapılmaz.


🛠️ Kullanım Rehberi

1. İnteraktif Terminal Oturumu (REPL)

Terminalde doğrudan .\acta yazarak oturumu başlatabilirsiniz:

.\acta.cmd

Oturum esnasında kullanabileceğiniz kısayol komutları (Slash Commands):

  • /menu: Sohbet geçmişini ve yüklü belgeyi silmeden oturum başlangıç ekranını (model, belge ve gizlilik durumu) yeniden gösterir.
  • /file <dosya-yolu>: Bir PDF veya DOCX tez taslağını yerel olarak Markdown'a çevirip hafızaya alır (Örn: /file "./tez taslak.docx").
  • /doc: Şu an yüklü olan belgenin kelime sayısı, yaklaşık token miktarı ve durumunu gösterir.
  • /model <sağlayıcı> [model]: Aktif modeli oturum esnasında değiştirir (Örn: /model deepseek deepseek-reasoner veya /model claude).
  • /key <sağlayıcı> <key>: API anahtarınızı güvenle kaydeder (Örn: /key gemini AIzaSy...).
  • /lang <kod>: Danışmanlık dilini anında değiştirir (Örn: /lang tr, /lang en, /lang de).
  • /privacy: PII (Kişisel Veri) anonimleştirme kalkanını açar veya kapatır.
  • /clear: Sohbet geçmişini sıfırlar (yüklü belge korunur).
  • /export [dosya-yolu]: Soru-cevap turlarını JSON'a; .md uzantılı yol verilirse Markdown'a kaydeder.
  • /update: npm'deki en son sürümü kontrol eder; onayınızla yalnızca global npm kurulumunu günceller. Kaynak koddan veya global npm dışından çalışırken otomatik güncelleme yapmaz.
  • /critique: Sert hakem bakışıyla mantık, kanıt ve metodoloji eleştirisi sunar.
  • /methodology: Yöntemleri karşılaştırır; değişken, kontrol grubu, karıştırıcı etken ve riskleri sorularla sorgular.
  • /stats-help: Araştırma tasarımı ve veri yapısına uygun istatistiksel test ve varsayım kontrollerine yönlendirir.
  • /literature-review: Sağlanan literatürü tematik olarak uzlaşı, tartışma ve araştırma boşluklarına ayırır; kaynak uydurmaz.
  • /thesis-plan: Teslim tarihinden geriye doğru bölüm yol haritası, haftalık hedefler ve bu hafta için üç eylem çıkarır.
  • /next-steps: Sonraki araştırma aşamasını ve bu hafta için üç net eylemi belirler.
  • /outline: Kelime hedefleri belirtilmiş başlık iskeleti oluşturur.
  • /slide-outline: Çalışmayı 10 slaytlık sunum planına dönüştürür.
  • /fact-check: İddiaların kanıt düzeyini değerlendirir ve doğrulama gereksinimlerini işaretler.
  • /citation: Atıf stili tutarlılığını ve eksik künye bilgilerini denetler.
  • /latex-help: LaTeX hatasının olası kök nedenini ve çözüm yolunu açıklar.
  • /revise-guide: Metni yeniden yazmadan satır bazlı, kavramsal revizyon notları verir.
  • /help: Türkçe ve İngilizce komut yardımını listeler.
  • /exit: Programdan çıkar.

Akademik komutlar SKILL.md içindeki akademik dürüstlük ilkelerine uyar: hazır teslim metni yerine eleştirel ve Sokratik rehberlik sunar. /revise-guide gönderilen metni yeniden yazmaz veya başka sözcüklerle ifade etmez.

Windows .exe içindeki komutları denemek için kaynak kod değişikliklerinden sonra npm run build:exe çalıştırın; ardından .\Acta Socratica.exe dosyasını açıp /help veya /menu yazın. Örnek: /critique Araştırma sorumu değerlendir: ... ya da /slide-outline .... Akademik komutlar için yapılandırılmış bir AI sağlayıcısı/API anahtarı ve internet bağlantısı gerekir. Paketlenmiş .exe, global npm kurulumu olmadığından /update ile kendi üzerine güncellenmez; kaynak kod güncellendikten sonra yeniden derlenmelidir.

Windows CMD'de kopyalanan metni yapıştırmak için sağ tıklayın; Windows Terminal'de Ctrl+Shift+V kullanın. Dosya yolunu /file komutuna tırnak içinde verebilirsiniz.

2. Tek Komutla Belge İnceleme

Bir dosyayı doğrudan başlatırken yüklemek için:

.\acta.cmd chat ./tezim.docx

3. Yerel Markdown Dönüştürücü Aracı

Herhangi bir PDF veya Word belgesini AI'a göndermeksizin yalnızca temiz bir Markdown dosyasına dönüştürmek için:

.\acta.cmd convert ./makale.pdf ./makale_temiz.md

4. API Anahtarlarını Yapılandırma

Anahtarlarınızı terminalden veya bir .env dosyası oluşturarak tanımlayabilirsiniz:

# Terminalden kalıcı kaydetme:
.\acta.cmd config --gemini "GEMINI_API_KEY_BURAYA"
.\acta.cmd config --anthropic "CLAUDE_API_KEY_BURAYA"
.\acta.cmd config --deepseek "DEEPSEEK_API_KEY_BURAYA"
.\acta.cmd config --openai "OPENAI_API_KEY_BURAYA"
.\acta.cmd config --qwen "QWEN_API_KEY_BURAYA"

# Varsayılan sağlayıcıyı seçme:
.\acta.cmd config --provider deepseek --model deepseek-reasoner

Veya .env dosyası ile:

GEMINI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
DEEPSEEK_API_KEY=your_key_here
DASHSCOPE_API_KEY=your_key_here

🔒 Güvenlik ve Veri Koruması Taahhüdü

  1. İnternetsiz Yerel Dosya Ayrıştırma: Yüklediğiniz Word ve PDF dosyaları üçüncü taraf bir bulut dönüştürücüsüne asla gitmez. Ayrıştırma işlemi yerel Node.js motorunda gerçekleşir.
  2. Kişisel Veri Maskeleme: Metinlerinizdeki e-posta adresleri, TC kimlik numaraları, telefonlar ve gizli API anahtarları otomatik olarak algılanıp sansürlenir ([REDACTED_...]).
  3. Şifreli ve Yerel Ayarlar: API anahtarlarınız asla uzak bir sunucuya veya Git reposuna gönderilmez; işletim sisteminizin yerel profil dizininde saklanır.
  4. Yerel Oturum Dışa Aktarımı: /export ile soru-cevap turları yerel JSON veya Markdown dosyasına kaydedilir.

📜 Lisans

Bu proje MIT Lisansı ile lisanslanmıştır. Akademik ve kişisel araştırmalarınızda dilediğiniz gibi geliştirebilir, modifiye edebilir ve kullanabilirsiniz.

💬 Görüş ve İletişim

Görüşlerinizi, önerilerinizi ve yorumlarınızı paylaşabilirsiniz:


Changelog / Sürüm Notları

0.2.0

  • English: Initial release of the interactive CLI, local document conversion, privacy redaction, and multi-provider AI support. Added current model defaults, opt-in updates for global npm installations, startup version display, and response time/token telemetry in chat and exports.
  • Türkçe: Etkileşimli CLI, yerel belge dönüştürme, kişisel veri maskeleme ve çoklu AI sağlayıcı desteğinin ilk sürümü. Güncel model varsayılanları, global npm kurulumu için isteğe bağlı güncelleme, açılışta sürüm gösterimi ve yanıtlarda/dışa aktarımlarda süre-token telemetrisi eklendi.