{"id":31734925,"url":"https://github.com/graves/awful_aj","last_synced_at":"2025-10-09T09:03:54.026Z","repository":{"id":199911211,"uuid":"704276750","full_name":"graves/awful_aj","owner":"graves","description":"CLI tool for OpenAI compatible APIs","archived":false,"fork":false,"pushed_at":"2025-10-03T01:25:13.000Z","size":64280,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-03T01:26:52.955Z","etag":null,"topics":["agentic-ai","agents","cli","embedded","llm","prompt-engineering","rust","vector-database"],"latest_commit_sha":null,"homepage":"https://awful-aj.awfulsec.com/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/graves.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-10-12T23:35:09.000Z","updated_at":"2025-10-03T01:25:17.000Z","dependencies_parsed_at":"2023-10-13T12:15:21.995Z","dependency_job_id":"b983b385-1245-4dd5-a177-ef7fe2af6105","html_url":"https://github.com/graves/awful_aj","commit_stats":null,"previous_names":["graves/awful_aj"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/graves/awful_aj","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graves%2Fawful_aj","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graves%2Fawful_aj/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graves%2Fawful_aj/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graves%2Fawful_aj/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graves","download_url":"https://codeload.github.com/graves/awful_aj/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graves%2Fawful_aj/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001172,"owners_count":26083021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agents","cli","embedded","llm","prompt-engineering","rust","vector-database"],"created_at":"2025-10-09T09:00:59.477Z","updated_at":"2025-10-09T09:03:54.020Z","avatar_url":"https://github.com/graves.png","language":"Rust","funding_links":[],"categories":["Applications","LLM Tools"],"sub_categories":["Productivity"],"readme":"# Awful Jade (`aj`) 🌲\n\n[![Crates.io](https://img.shields.io/crates/v/awful_aj.svg)](https://crates.io/crates/awful_aj)\n[![Docs.rs](https://docs.rs/awful_aj/badge.svg)](https://docs.rs/awful_aj)\n\n**Awful Jade** (aka **`aj`**) is your command-line sidekick for working with Large Language Models (LLMs).  \n\nThink of it as an _LLM Swiss Army knife with the best intentions_ 😇.\n\n\u003e Ask questions, run interactive sessions, sanitize messy OCR book dumps, synthesize exam questions, all without leaving your terminal.\n\nIt’s built in Rust for speed, safety, and peace of mind. 🦀\n\n---\n\n```\nλ aj --help\nAwful Jade – a CLI for local LLM tinkering with memories, templates, and vibes.\n\nUsage: aj \u003cCOMMAND\u003e\n\nCommands:\n  ask          Ask a single question and print the assistant’s response\n  interactive  Start an interactive REPL-style conversation\n  init         Initialize configuration and default templates in the platform config directory\n  help         Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help     Print help\n  -V, --version  Print version\n```\n\n---\n\n![Awful Jade CLI tool logo](aj.jpeg)\n\n---\n\n## ✨ Features\n\n- **Ask the AI**: Run `aj ask \"question\"` and get answers powered by your configured model.  \n- **Interactive Mode**: A REPL-style conversation with memory \u0026 vector search (your AI “remembers” past context).  \n- **Vector Store**: Uses HNSW + sentence embeddings to remember what you’ve said before. Basically, your AI gets a brain. 🧠  \n- **Brains with Limits**: Keeps only as many tokens as you allow. When full, it forgets the oldest stuff. (Like you after 3 AM pizza.)  \n- **Config \u0026 Templates**: YAML-driven configs and prompt templates. Customize everything, break nothing.  \n- **Auto-downloads BERT embeddings model**: If the required `all-mini-lm-l12-v2` model isn’t around, `aj` will politely fetch and unzip it into your config dir.  \n\n---\n\n## 📦 Installation\n\nFrom [crates.io](https://crates.io/crates/awful_aj):\n\n```bash\ncargo install awful_aj\n```\n\nThis gives you the `aj` binary.\n\nRequirements:\n- Rust (use rustup if you don’t have it).\n- Diesel CLI if you want to reset or migrate the session DB.\n- Python 3.11 and pytorch 2.4.0.\n  \nThe BERT embeddings model (all-mini-lm-l12-v2) will be downloaded automatically into your platform’s config directory:\n- macOS: `~/Library/Application Support/com.awful-sec.aj/`\n- Linux: `~/.config/aj/`\n- Windows: `C:\\Users\\YOU\\AppData\\Roaming\\awful-sec\\aj/`\n\n---\n\n## 👷🏽‍♀️ Setup (steps will vary according to your operating system)\n\n1. Install conda python version manager.\n\n```bash\nbrew install miniconda\n```\n\n2. Create Python 3.11 virtual environment named aj and activate it.\n\n```bash\nconda create -n aj python=3.11\nconda activate aj\n````\n\n3. Install pytorch 2.4.0\n\n```bash\npip install torch==2.4.0\n````\n\n4. Add the following to your shell initialization.\n\n```bash\nexport LIBTORCH_USE_PYTORCH=1\nexport LIBTORCH='/opt/homebrew/Caskroom/miniconda/base/pkgs/pytorch-2.4.0-py3.11_0/lib/python3.11/site-packages/torch' # Or wherever Conda installed libtorch on your OS\nexport DYLD_LIBRARY_PATH=\"$LIBTORCH/lib\"\n```\n\n---\n\n## 🚀 Usage\n\n1. Initialize\n\nCreate default configs and templates:\n\n```\naj init\n```\n\nThis will generate:\n- `config.yaml` with sensible defaults\n- `templates/default.yaml` and `templates/simple_question.yaml`\n- A SQLite database (`aj.db`) for sessions\n\n---\n\n2. Ask a Question\n\n```\naj ask \"Is Bibi really from Philly?\"\n```\n\nYou’ll get a colorful, model-dependent answer.\n\n![aj ask command](./bibi.gif)\n\n---\n\n3. Interactive Mode\n\nTalk with the AI like it’s your therapist, mentor, or rubber duck:\n\n```\naj interactive\n```\n\nSupports memory via the vector store, so it won’t immediately forget your name.\n_(Unlike your barista.)_\n\n![aj interactive command](./interactive.gif)\n\n---\n\n4. Configuration\n\nEdit your config at:\n\n```\n~/.config/aj/config.yaml   # Linux\n~/Library/Application Support/com.awful-sec.aj/config.yaml   # macOS\n```\n\nExample:\n\n```\napi_base: \"http://localhost:1234/v1\"\napi_key: \"CHANGEME\"\nmodel: \"jade_qwen3_4b_mlx\"\ncontext_max_tokens: 8192\nassistant_minimum_context_tokens: 2048\nstop_words:\n  - \"\u003c|im_end|\u003e\\\\n\u003c|im_start|\u003e\"\n  - \"\u003c|im_start|\u003e\\n\"\nsession_db_url: \"/Users/you/Library/Application Support/com.awful-sec.aj/aj.db\"\n```\n\n---\n\n5. Templates\n\nTemplates are YAML files in your config directory.\nHere’s a baby template:\n\n```\nsystem_prompt: \"You are Awful Jade, a helpful AI assistant programmed by Awful Security.\"\nmessages: []\n```\n\nAdd more, swap them in with `--template \u003cname\u003e`.\n\n---\n\n## 🧠 How it Works\n- **Brain**: Keeps memories in a deque, trims when it gets too wordy.\n- **VectorStore**: Embeds your inputs using all-mini-lm-l12-v2, saves to HNSW index.\n- **Config**: YAML-based, sane defaults, easy to tweak.\n- **Templates**: Prompt engineering without copy-pasting into your terminal like a caveman.\n- **Ensure All Mini**: If the BERT model’s not there, AJ fetches it automagically.\n\n---\n\n## 🧑‍💻 Development\n\nClone, hack, repeat:\n\n```\ngit clone https://github.com/graves/awful_aj.git\ncd awful_aj\ncargo build\n```\n\nRun tests:\n\n```\ncargo test\n```\n\n---\n\n## 🤝 Contributing\n\nPRs welcome!\nBugs, docs, new templates, vector hacks—bring it on.\nBut remember: with great power comes great YAML.\n\n---\n\n## 📜 License\n\nMIT. Do whatever you want, just don’t blame us when your AI remembers your browser history.\n\n---\n\n💡 Awful Jade: bad name, good brain.\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraves%2Fawful_aj","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraves%2Fawful_aj","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraves%2Fawful_aj/lists"}