acta-socratica
v0.2.1
Published
Terminal-based Socratic Academic Advisor & Autonomous Research Agent for Universities and Scholars
Maintainers
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
actaFor 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
actaAvailable 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, ores)./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.docxConvert a document locally
Convert a PDF or Word document to Markdown without sending it to an AI provider:
acta convert ./paper.pdf ./paper_clean.mdConfigure 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-reasonerOr 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
- Local document parsing: Word and PDF files are parsed by the local Node.js process, not by a third-party document conversion service.
- 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.
- Local settings: API keys are stored in the user's local profile and are not sent to this project's servers.
- Local session export:
/exportsaves 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:
- Project repository: Acta Socratica on GitHub
- LinkedIn: Furkan Kerim Arda
- GitHub: Furkankerimarda
- Email: [email protected]
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 devGlobal 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.cmdOturum 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-reasonerveya/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;.mduzantı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.docx3. 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.md4. 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-reasonerVeya .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ü
- İ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.
- Kişisel Veri Maskeleme: Metinlerinizdeki e-posta adresleri, TC kimlik numaraları, telefonlar ve gizli API anahtarları otomatik olarak algılanıp sansürlenir (
[REDACTED_...]). - Ş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.
- Yerel Oturum Dışa Aktarımı:
/exportile 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:
- Proje deposu: GitHub'da Acta Socratica
- LinkedIn: Furkan Kerim Arda
- GitHub: Furkankerimarda
- E-posta: [email protected]
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.
