mforege 0.1.0__tar.gz

mforege-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Munjur
+
+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.

mforege-0.1.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: mforege
+Version: 0.1.0
+Summary: MForege — a personal AI agent CLI with tools, memory, and an IDE-style terminal UI
+Author-email: Munjur Alom <munjuralom.devs@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/munjurdev/MForege
+Project-URL: Repository, https://github.com/munjurdev/MForege
+Project-URL: Issues, https://github.com/munjurdev/MForege/issues
+Project-URL: Changelog, https://github.com/munjurdev/MForege/releases
+Keywords: ai,agent,cli,assistant,llm,openai,ollama,groq,tools,chatbot
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai==3.13.0
+Requires-Dist: python-decouple==3.8
+Requires-Dist: exa-py==2.20.0
+Requires-Dist: prompt_toolkit==3.0.53
+Provides-Extra: dev
+Requires-Dist: pytest==8.4.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# MForege — AI Agent CLI
+
+[![PyPI version](https://img.shields.io/pypi/v/mforege.svg)](https://pypi.org/project/mforege/)
+[![Python](https://img.shields.io/pypi/pyversions/mforege.svg)](https://pypi.org/project/mforege/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A command-line AI agent with a transparent, IDE-style interface: live tool
+activity, colored diffs on every file change, mission plans, and long-term
+memory. Supports OpenAI, Ollama (free & local), and any OpenAI-compatible
+API (Groq, Together, etc.).
+
+## Install
+
+```bash
+pip install mforege
+```
+
+Or with [pipx](https://pipx.pypa.io) (recommended for CLIs — isolated env,
+command on PATH everywhere):
+
+```bash
+pipx install mforege
+```
+
+Or straight from source:
+
+```bash
+pip install git+https://github.com/munjurdev/MForege.git
+```
+
+## Features
+
+### Agent core
+
+- **Full tool loop** — when the model calls a tool, the result is sent back so
+  the model can use it in its answer (streaming and non-streaming); up to 10
+  rounds per message, configurable via `AgentConfig.max_tool_rounds`
+- **Streaming output** — responses appear token by token, with a
+  `thinking Ns...` timer while the model works
+- **Personality + response control** — friendly, witty, emoji-moderate; short
+  answers for casual chat, clarifying questions for ambiguous or underspecified
+  requests (never dumps giant tutorials or acts on invented details)
+
+### Tools
+
+| Tool | Purpose |
+|------|---------|
+| `list_files` | List directories (workspace-confined) |
+| `read_file` | Read text files with line numbers; `offset`/`limit` windows for big files |
+| `search_code` | Regex search across the project (`file:line: match`), noise dirs skipped |
+| `glob_files` | Find files by pattern, recursively (`**/*.py`), newest first |
+| `run_command` | Shell commands with a 3-tier safety model |
+| `create_file` | New files (parent folders auto-created) |
+| `edit_file` | Exact, unique-snippet replacement |
+| `todo_plan` | Visible step-by-step mission plan |
+| `calculator` | Safe AST-based math (no `eval`) |
+| `get_current_time` | Current date/time |
+| `web_search` | Live web search via Exa (needs `EXA_API_KEY`) |
+
+### Safety
+
+- **Destructive commands blocked** outright (`rm -rf`, `git push --force`,
+  `format`, ...)
+- **Mutating actions require approval** — file writes/edits show a colored
+  diff before you confirm; commands show the exact line to be run
+- **Fail-closed** — without a confirmation handler, mutating operations refuse
+  rather than run unconfirmed
+- **Workspace-confined** — path tools only operate inside the folder you
+  choose at launch; `../` and symlink escapes are rejected
+- **Timeouts & caps** — 30s command timeout, tool output capped so the context
+  window never balloons
+
+### Chat-style interface (prompt_toolkit)
+
+- **Bottom input box** — the input stays pinned at the bottom like a chat app;
+  the transcript scrolls above it
+- **Live activity stream** — every tool call prints as `· tool(args) ✓ (0.3s)`
+- **Thinking timer** — `thinking Ns...` runs until the first token arrives
+- **Colored diffs** — `+` green / `-` red, shown before approval *and* in the
+  transcript after the edit lands
+- **Plan statusline** — `[Plan 2/5] next: write the test` after each reply
+- **Status bar** — model, workspace, and shortcut hints always visible
+- **Keys** — Enter sends, Alt+Enter adds a newline, Ctrl+C quits
+- **Slash commands** — `/help`, `/plan`, `/tools`, `/memory`, `/forget`,
+  `/clear`, `/exit`
+
+### Memory
+
+- **Conversation memory** — history per session, `clear` resets it
+- **Long-term memory** — after each reply a side-call asks *"did I learn
+  anything durable?"*; facts (name, projects, preferences) are saved to
+  `data/memory.json` (git-ignored) and injected into future sessions.
+  Personalized greeting on startup ("Welcome back, Munjur! 👋")
+
+### Resilience
+
+- Request timeouts + automatic retries with backoff for transient failures
+- Friendly errors for missing keys or Ollama not running
+- UTF-8 output on Windows (emoji-safe), clean async shutdown
+
+## Setup
+
+```bash
+python -m venv env
+env/Scripts/activate          # Windows (bash: source env/Scripts/activate)
+pip install -r requirements.txt
+pip install -e .              # installs the `mforege` command
+```
+
+After `pip install -e .`, MForege works from **any** terminal — including VS
+Code's — with the venv activated:
+
+```bash
+mforege                                    # in any folder (uses MForege's own .env)
+mforege --workspace "C:\path\to\project"   # work inside another project
+```
+
+### Backends
+
+**OpenAI** — put your key in `.env`:
+
+```
+OPENAI_API_KEY=sk-...
+LLM_MODEL=gpt-4o-mini
+```
+
+**Ollama (free, local)** — install from https://ollama.com, then:
+
+```bash
+ollama pull llama3
+mforege --backend ollama --model llama3
+```
+
+**Custom (e.g., Groq)**:
+
+```
+API_KEY=gsk_...
+BASE_URL=https://api.groq.com/openai/v1
+LLM_MODEL=llama-3.1-8b-instant
+```
+
+### Web search (optional)
+
+1. Get a free API key at https://dashboard.exa.ai
+2. Add to `.env`: `EXA_API_KEY=your_key`
+3. Restart the CLI
+
+### Workspace
+
+MForege can only read/write inside one folder — the one you choose:
+
+```bash
+mforege --workspace "C:\path\to\your\project"
+```
+
+The header shows the active workspace. To work in a different folder, restart
+with a different `--workspace` (or set `WORKSPACE` in `.env`).
+
+## Run
+
+```bash
+python main.py                  # from the project folder
+mforege                         # from ANY folder (after pip install -e .)
+mforege --backend ollama --model llama3
+mforege --workspace "C:\path\to\your\project"
+```
+
+`.env` resolution: if the current folder has a `.env`, it wins; otherwise
+MForege falls back to its own `.env` — so API keys are found no matter where
+you launch it. Workspace defaults to the current directory.
+
+## CLI commands
+
+| Command  | Action                                     |
+|----------|--------------------------------------------|
+| `/help`  | Show the command menu                      |
+| `/plan`  | Show the current mission plan              |
+| `/tools` | List registered tools                      |
+| `/memory`| Show what MForege remembers about you      |
+| `/forget`| Wipe long-term memory                      |
+| `/clear` | Reset conversation (current session)       |
+| `/exit`  | Quit (plain `exit` also works)             |
+
+## Example session
+
+```
+Welcome back, Munjur! 👋
+(I remember 2 things)
+
+You: create utils.py with a greet function, then test it
+Assistant: thinking 2s...
+  · todo_plan(action=set) ✓ (0.0s)
+  · create_file(path=utils.py) ✓ (0.0s)
+[?] MForege wants to: CREATE file 'utils.py' (95 chars)
+  @@ -0,0 +1,3 @@
+  +def greet(name):
+  +    return f"Hello, {name}!"
+    Allow? [y/N]: y
+  ✓ Edit applied:
+  @@ -0,0 +1,3 @@
+  +def greet(name):
+  ...
+[Plan 2/4] next: run the tests
+```
+
+## Adding your own tool
+
+```python
+from app.agent.tools import create_tool
+
+async def get_weather(city: str):
+    return f"Sunny in {city}, 25C"
+
+agent.register_tools(create_tool("get_weather", "Get weather for a city", get_weather))
+```
+
+## Tests
+
+```bash
+env/Scripts/python -m pytest
+```
+
+161 tests covering conversation memory, the tool registry, the safe
+calculator, the web search tool, long-term memory (store, injection,
+extraction), system tools (path confinement, command classification,
+confirmation flow — sync and async, diffs, notifications), discovery tools
+(search/glob/read windows), the todo plan, and the agent's tool-call loop —
+all with a mocked LLM, no network needed.

mforege-0.1.0/README.md

@@ -0,0 +1,228 @@
+# MForege — AI Agent CLI
+
+[![PyPI version](https://img.shields.io/pypi/v/mforege.svg)](https://pypi.org/project/mforege/)
+[![Python](https://img.shields.io/pypi/pyversions/mforege.svg)](https://pypi.org/project/mforege/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A command-line AI agent with a transparent, IDE-style interface: live tool
+activity, colored diffs on every file change, mission plans, and long-term
+memory. Supports OpenAI, Ollama (free & local), and any OpenAI-compatible
+API (Groq, Together, etc.).
+
+## Install
+
+```bash
+pip install mforege
+```
+
+Or with [pipx](https://pipx.pypa.io) (recommended for CLIs — isolated env,
+command on PATH everywhere):
+
+```bash
+pipx install mforege
+```
+
+Or straight from source:
+
+```bash
+pip install git+https://github.com/munjurdev/MForege.git
+```
+
+## Features
+
+### Agent core
+
+- **Full tool loop** — when the model calls a tool, the result is sent back so
+  the model can use it in its answer (streaming and non-streaming); up to 10
+  rounds per message, configurable via `AgentConfig.max_tool_rounds`
+- **Streaming output** — responses appear token by token, with a
+  `thinking Ns...` timer while the model works
+- **Personality + response control** — friendly, witty, emoji-moderate; short
+  answers for casual chat, clarifying questions for ambiguous or underspecified
+  requests (never dumps giant tutorials or acts on invented details)
+
+### Tools
+
+| Tool | Purpose |
+|------|---------|
+| `list_files` | List directories (workspace-confined) |
+| `read_file` | Read text files with line numbers; `offset`/`limit` windows for big files |
+| `search_code` | Regex search across the project (`file:line: match`), noise dirs skipped |
+| `glob_files` | Find files by pattern, recursively (`**/*.py`), newest first |
+| `run_command` | Shell commands with a 3-tier safety model |
+| `create_file` | New files (parent folders auto-created) |
+| `edit_file` | Exact, unique-snippet replacement |
+| `todo_plan` | Visible step-by-step mission plan |
+| `calculator` | Safe AST-based math (no `eval`) |
+| `get_current_time` | Current date/time |
+| `web_search` | Live web search via Exa (needs `EXA_API_KEY`) |
+
+### Safety
+
+- **Destructive commands blocked** outright (`rm -rf`, `git push --force`,
+  `format`, ...)
+- **Mutating actions require approval** — file writes/edits show a colored
+  diff before you confirm; commands show the exact line to be run
+- **Fail-closed** — without a confirmation handler, mutating operations refuse
+  rather than run unconfirmed
+- **Workspace-confined** — path tools only operate inside the folder you
+  choose at launch; `../` and symlink escapes are rejected
+- **Timeouts & caps** — 30s command timeout, tool output capped so the context
+  window never balloons
+
+### Chat-style interface (prompt_toolkit)
+
+- **Bottom input box** — the input stays pinned at the bottom like a chat app;
+  the transcript scrolls above it
+- **Live activity stream** — every tool call prints as `· tool(args) ✓ (0.3s)`
+- **Thinking timer** — `thinking Ns...` runs until the first token arrives
+- **Colored diffs** — `+` green / `-` red, shown before approval *and* in the
+  transcript after the edit lands
+- **Plan statusline** — `[Plan 2/5] next: write the test` after each reply
+- **Status bar** — model, workspace, and shortcut hints always visible
+- **Keys** — Enter sends, Alt+Enter adds a newline, Ctrl+C quits
+- **Slash commands** — `/help`, `/plan`, `/tools`, `/memory`, `/forget`,
+  `/clear`, `/exit`
+
+### Memory
+
+- **Conversation memory** — history per session, `clear` resets it
+- **Long-term memory** — after each reply a side-call asks *"did I learn
+  anything durable?"*; facts (name, projects, preferences) are saved to
+  `data/memory.json` (git-ignored) and injected into future sessions.
+  Personalized greeting on startup ("Welcome back, Munjur! 👋")
+
+### Resilience
+
+- Request timeouts + automatic retries with backoff for transient failures
+- Friendly errors for missing keys or Ollama not running
+- UTF-8 output on Windows (emoji-safe), clean async shutdown
+
+## Setup
+
+```bash
+python -m venv env
+env/Scripts/activate          # Windows (bash: source env/Scripts/activate)
+pip install -r requirements.txt
+pip install -e .              # installs the `mforege` command
+```
+
+After `pip install -e .`, MForege works from **any** terminal — including VS
+Code's — with the venv activated:
+
+```bash
+mforege                                    # in any folder (uses MForege's own .env)
+mforege --workspace "C:\path\to\project"   # work inside another project
+```
+
+### Backends
+
+**OpenAI** — put your key in `.env`:
+
+```
+OPENAI_API_KEY=sk-...
+LLM_MODEL=gpt-4o-mini
+```
+
+**Ollama (free, local)** — install from https://ollama.com, then:
+
+```bash
+ollama pull llama3
+mforege --backend ollama --model llama3
+```
+
+**Custom (e.g., Groq)**:
+
+```
+API_KEY=gsk_...
+BASE_URL=https://api.groq.com/openai/v1
+LLM_MODEL=llama-3.1-8b-instant
+```
+
+### Web search (optional)
+
+1. Get a free API key at https://dashboard.exa.ai
+2. Add to `.env`: `EXA_API_KEY=your_key`
+3. Restart the CLI
+
+### Workspace
+
+MForege can only read/write inside one folder — the one you choose:
+
+```bash
+mforege --workspace "C:\path\to\your\project"
+```
+
+The header shows the active workspace. To work in a different folder, restart
+with a different `--workspace` (or set `WORKSPACE` in `.env`).
+
+## Run
+
+```bash
+python main.py                  # from the project folder
+mforege                         # from ANY folder (after pip install -e .)
+mforege --backend ollama --model llama3
+mforege --workspace "C:\path\to\your\project"
+```
+
+`.env` resolution: if the current folder has a `.env`, it wins; otherwise
+MForege falls back to its own `.env` — so API keys are found no matter where
+you launch it. Workspace defaults to the current directory.
+
+## CLI commands
+
+| Command  | Action                                     |
+|----------|--------------------------------------------|
+| `/help`  | Show the command menu                      |
+| `/plan`  | Show the current mission plan              |
+| `/tools` | List registered tools                      |
+| `/memory`| Show what MForege remembers about you      |
+| `/forget`| Wipe long-term memory                      |
+| `/clear` | Reset conversation (current session)       |
+| `/exit`  | Quit (plain `exit` also works)             |
+
+## Example session
+
+```
+Welcome back, Munjur! 👋
+(I remember 2 things)
+
+You: create utils.py with a greet function, then test it
+Assistant: thinking 2s...
+  · todo_plan(action=set) ✓ (0.0s)
+  · create_file(path=utils.py) ✓ (0.0s)
+[?] MForege wants to: CREATE file 'utils.py' (95 chars)
+  @@ -0,0 +1,3 @@
+  +def greet(name):
+  +    return f"Hello, {name}!"
+    Allow? [y/N]: y
+  ✓ Edit applied:
+  @@ -0,0 +1,3 @@
+  +def greet(name):
+  ...
+[Plan 2/4] next: run the tests
+```
+
+## Adding your own tool
+
+```python
+from app.agent.tools import create_tool
+
+async def get_weather(city: str):
+    return f"Sunny in {city}, 25C"
+
+agent.register_tools(create_tool("get_weather", "Get weather for a city", get_weather))
+```
+
+## Tests
+
+```bash
+env/Scripts/python -m pytest
+```
+
+161 tests covering conversation memory, the tool registry, the safe
+calculator, the web search tool, long-term memory (store, injection,
+extraction), system tools (path confinement, command classification,
+confirmation flow — sync and async, diffs, notifications), discovery tools
+(search/glob/read windows), the todo plan, and the agent's tool-call loop —
+all with a mocked LLM, no network needed.

mforege-0.1.0/app/__init__.py

@@ -0,0 +1,3 @@
+"""MForege — a personal AI agent CLI with tools, memory, and an IDE-style terminal UI."""
+
+__version__ = "0.1.0"

mforege-0.1.0/app/agent/__init__.py

@@ -0,0 +1,10 @@
+"""
+AI Agent Package
+"""
+from ..llm import LLMClient
+from .agent import Agent, AgentConfig
+from .memory import ConversationMemory, Message
+from .long_term_memory import LongTermMemory
+from .tools import Tool, ToolRegistry, CalculatorTool, TimeTool
+
+__all__ = ["Agent", "AgentConfig", "LLMClient", "ConversationMemory", "Message", "LongTermMemory", "Tool", "ToolRegistry", "CalculatorTool", "TimeTool"]