hitmos 0.0.1__py3-none-any.whl

hitmos/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

hitmos/app.py

@@ -0,0 +1,163 @@
+import asyncio
+from collections.abc import AsyncGenerator
+from pathlib import Path
+
+from .chat import ChatSession
+from .client import OpenRouterClient, ToolCallRequest
+from .commands import CommandHandler, CommandResult, CommandType
+from .config import ConfigManager
+from .constants import SYSTEM_PROMPT
+from .context import ProjectContext
+from .exceptions import AuthError, HitmosError
+from .methods import dispatch
+from .ui import ConsoleUI
+
+
+class HitmosApp:
+    def __init__(self) -> None:
+        self._config = ConfigManager()
+        self._ui = ConsoleUI()
+        self._commands = CommandHandler()
+        self._session: ChatSession | None = None
+        self._client: OpenRouterClient | None = None
+
+    def run(self) -> None:
+        try:
+            token = self._config.resolve_token()
+        except AuthError as e:
+            self._ui.show_error(str(e))
+            raise SystemExit(1)
+
+        model = self._config.get_model()
+        self._client = OpenRouterClient(token, model)
+
+        system_prompt, ctx_kb = self._build_system_prompt()
+        self._session = ChatSession(system_prompt=system_prompt)
+
+        self._ui.show_welcome(model, ctx_kb)
+
+        try:
+            asyncio.run(self._loop())
+        except KeyboardInterrupt:
+            self._ui.show_exit()
+
+    async def _loop(self) -> None:
+        assert self._client is not None
+        assert self._session is not None
+
+        while True:
+            try:
+                text = await self._ui.get_input()
+            except (KeyboardInterrupt, EOFError):
+                self._ui.show_exit()
+                return
+
+            text = text.strip()
+            if not text:
+                continue
+
+            result = self._commands.parse(text)
+            if result is not None:
+                should_exit = await self._handle_command(result)
+                if should_exit:
+                    return
+            else:
+                await self._handle_message(text)
+
+    def _build_system_prompt(self) -> tuple[str, int]:
+        ctx, kb = ProjectContext(Path.cwd()).build()
+        if not ctx:
+            return SYSTEM_PROMPT, 0
+        return (
+            "You are Hitmos, a helpful AI coding assistant. "
+            "Be concise, accurate, and developer-focused.\n\n"
+            "You have access to the user's project files below. "
+            "Use this context to give accurate, project-specific answers.\n\n"
+            + ctx,
+            kb,
+        )
+
+    async def _handle_command(self, result: CommandResult) -> bool:
+        assert self._client is not None
+        assert self._session is not None
+
+        match result.type:
+            case CommandType.HELP:
+                self._ui.show_help()
+            case CommandType.CLEAR:
+                self._session.clear()
+                self._ui.show_info("History cleared.")
+            case CommandType.RESET:
+                self._session.reset()
+                self._ui.show_info("Context reset.")
+            case CommandType.MODEL:
+                if result.arg:
+                    self._client.model = result.arg
+                    self._config.save_model(result.arg)
+                    self._ui.show_success(f"Model: {result.arg}")
+                else:
+                    selected = await self._ui.show_model_picker(self._client.model)
+                    if selected:
+                        self._client.model = selected
+                        self._config.save_model(selected)
+                        self._ui.show_success(f"Model: {selected}")
+            case CommandType.EXIT:
+                self._ui.show_exit()
+                return True
+        return False
+
+    async def _handle_message(self, text: str) -> None:
+        assert self._client is not None
+        assert self._session is not None
+
+        self._session.add_user(text)
+
+        try:
+            while True:
+                tool_calls: list[ToolCallRequest] = []
+
+                async def _text_gen() -> AsyncGenerator[str, None]:
+                    async for item in self._client.stream_chat(  # type: ignore[union-attr]
+                        self._session.messages  # type: ignore[union-attr]
+                    ):
+                        if isinstance(item, list):
+                            tool_calls.extend(item)
+                        else:
+                            yield item
+
+                full_response = await self._ui.stream_response(_text_gen())
+
+                if not tool_calls:
+                    if full_response:
+                        self._session.add_assistant(full_response)
+                    break
+
+                self._session.add_raw({
+                    "role": "assistant",
+                    "content": full_response or None,
+                    "tool_calls": [
+                        {
+                            "id": tc.id,
+                            "type": "function",
+                            "function": {"name": tc.name, "arguments": tc.arguments},
+                        }
+                        for tc in tool_calls
+                    ],
+                })
+
+                for tc in tool_calls:
+                    self._ui.show_tool_call(tc.name, tc.arguments)
+                    result = dispatch(tc.name, tc.arguments)
+                    self._ui.show_tool_result(result)
+                    self._session.add_raw({
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": result,
+                    })
+
+        except HitmosError as e:
+            self._session.pop_last()
+            self._ui.show_error(str(e))
+        except Exception as e:
+            self._session.pop_last()
+            self._ui.show_error(f"Unexpected error: {e}")

hitmos/chat.py

@@ -0,0 +1,34 @@
+from .constants import SYSTEM_PROMPT
+
+
+class ChatSession:
+    def __init__(self, system_prompt: str | None = None) -> None:
+        self._messages: list[dict] = []
+        self._system = system_prompt or SYSTEM_PROMPT
+
+    def add_user(self, content: str) -> None:
+        self._messages.append({"role": "user", "content": content})
+
+    def add_assistant(self, content: str) -> None:
+        self._messages.append({"role": "assistant", "content": content})
+
+    def add_raw(self, message: dict) -> None:
+        self._messages.append(message)
+
+    def clear(self) -> None:
+        self._messages.clear()
+
+    def reset(self) -> None:
+        self._messages.clear()
+
+    def pop_last(self) -> None:
+        if self._messages:
+            self._messages.pop()
+
+    @property
+    def messages(self) -> list[dict]:
+        return [{"role": "system", "content": self._system}] + self._messages
+
+    @property
+    def is_empty(self) -> bool:
+        return len(self._messages) == 0

hitmos/cli.py

@@ -0,0 +1,46 @@
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+
+app = typer.Typer(
+    name="hitmos",
+    help="Hitmos — AI terminal assistant",
+    add_completion=False,
+    no_args_is_help=False,
+)
+
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Start interactive Hitmos session."""
+    if ctx.invoked_subcommand is None:
+        from .app import HitmosApp
+
+        HitmosApp().run()
+
+
+@app.command("login")
+def login() -> None:
+    """Save OpenRouter API key to ~/.hitmos/config.toml."""
+    from .config import ConfigManager
+
+    console.print()
+    console.print("  [bold]Hitmos Login[/bold]")
+    console.print()
+
+    api_key = Prompt.ask("  Paste your OpenRouter API key", password=True)
+    api_key = api_key.strip()
+
+    if not api_key:
+        console.print("  [bold red]✖[/bold red]  No API key provided.")
+        raise typer.Exit(1)
+
+    ConfigManager().save_token(api_key)
+
+    console.print()
+    console.print(
+        "  [bold green]✓[/bold green]  API key saved to [dim]~/.hitmos/config.toml[/dim]"
+    )
+    console.print()

hitmos/client.py

@@ -0,0 +1,131 @@
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+
+import orjson
+from fasthttp import AsyncSession
+
+from .constants import APP_TITLE, HTTP_REFERER, OPENROUTER_CHAT_URL
+from .exceptions import APIError, AuthError, NetworkError, RateLimitError
+from .methods import ALL_TOOLS
+
+
+@dataclass
+class ToolCallRequest:
+    id: str
+    name: str
+    arguments: str
+
+
+class OpenRouterClient:
+    def __init__(self, token: str, model: str) -> None:
+        self._token = token
+        self._model = model
+
+    @property
+    def model(self) -> str:
+        return self._model
+
+    @model.setter
+    def model(self, value: str) -> None:
+        self._model = value
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._token}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": HTTP_REFERER,
+            "X-Title": APP_TITLE,
+        }
+
+    async def stream_chat(
+        self,
+        messages: list[dict],
+        use_tools: bool = True,
+    ) -> AsyncGenerator[str | list[ToolCallRequest], None]:
+        payload_dict: dict = {
+            "model": self._model,
+            "messages": messages,
+            "stream": True,
+            "max_tokens": 8192,
+        }
+        if use_tools:
+            payload_dict["tools"] = ALL_TOOLS
+            payload_dict["tool_choice"] = "auto"
+
+        payload = orjson.dumps(payload_dict)
+        pending: dict[int, dict] = {}
+
+        try:
+            async with AsyncSession(security=False, timeout=120.0) as session:
+                raw = session._ensure_open()
+                async with raw.stream(
+                    "POST",
+                    OPENROUTER_CHAT_URL,
+                    headers=self._headers(),
+                    content=payload,
+                    timeout=120.0,
+                ) as resp:
+                    await self._check_status(resp)
+                    async for line in resp.aiter_lines():
+                        token = self._parse_sse(line, pending)
+                        if token is not None:
+                            yield token
+        except (AuthError, RateLimitError, APIError):
+            raise
+        except Exception as exc:
+            msg = str(exc).lower()
+            if any(k in msg for k in ("connect", "timeout", "timed out", "network")):
+                raise NetworkError(str(exc)) from exc
+            raise NetworkError(f"Request failed: {exc}") from exc
+
+        if pending:
+            yield [
+                ToolCallRequest(id=v["id"], name=v["name"], arguments=v["arguments"])
+                for v in sorted(pending.values(), key=lambda x: x.get("index", 0))
+            ]
+
+    @staticmethod
+    async def _check_status(resp: object) -> None:
+        code: int = resp.status_code  # type: ignore[attr-defined]
+        if code == 401:
+            raise AuthError("Invalid API key.  Run: hitmos login")
+        if code == 429:
+            raise RateLimitError("Rate limit exceeded. Try again later.")
+        if code >= 400:
+            body = await resp.aread()  # type: ignore[attr-defined]
+            try:
+                err = orjson.loads(body)
+                msg = err.get("error", {}).get("message", f"HTTP {code}")
+            except Exception:
+                msg = f"HTTP {code}"
+            raise APIError(msg)
+
+    @staticmethod
+    def _parse_sse(line: str, pending: dict[int, dict]) -> str | None:
+        if not line.startswith("data: "):
+            return None
+        data = line[6:]
+        if data.strip() == "[DONE]":
+            return None
+        try:
+            chunk = orjson.loads(data)
+            delta = chunk["choices"][0]["delta"]
+
+            if content := delta.get("content"):
+                return content
+
+            for tc in delta.get("tool_calls", []):
+                idx = tc.get("index", 0)
+                if idx not in pending:
+                    pending[idx] = {"index": idx, "id": "", "name": "", "arguments": ""}
+                if tc.get("id"):
+                    pending[idx]["id"] = tc["id"]
+                fn = tc.get("function", {})
+                if fn.get("name"):
+                    pending[idx]["name"] = fn["name"]
+                if args := fn.get("arguments"):
+                    pending[idx]["arguments"] += args
+
+            return None
+        except (KeyError, IndexError, orjson.JSONDecodeError):
+            return None

hitmos/commands.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+from enum import Enum
+
+
+class CommandType(Enum):
+    HELP = "help"
+    CLEAR = "clear"
+    RESET = "reset"
+    MODEL = "model"
+    EXIT = "exit"
+
+
+@dataclass
+class CommandResult:
+    type: CommandType
+    arg: str | None = None
+
+
+class CommandHandler:
+    _MAP: dict[str, CommandType] = {
+        "/help": CommandType.HELP,
+        "/clear": CommandType.CLEAR,
+        "/reset": CommandType.RESET,
+        "/model": CommandType.MODEL,
+        "/exit": CommandType.EXIT,
+        "/quit": CommandType.EXIT,
+    }
+
+    def parse(self, text: str) -> CommandResult | None:
+        if not text.startswith("/"):
+            return None
+        parts = text.split(maxsplit=1)
+        cmd_type = self._MAP.get(parts[0].lower())
+        if cmd_type is None:
+            return None
+        arg = parts[1] if len(parts) > 1 else None
+        return CommandResult(type=cmd_type, arg=arg)

hitmos/config.py

@@ -0,0 +1,67 @@
+import tomllib
+
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from .constants import CONFIG_DIR, CONFIG_FILE, DEFAULT_MODEL
+from .exceptions import AuthError
+
+
+class _EnvSettings(BaseSettings):
+    model_config = SettingsConfigDict(case_sensitive=False, extra="ignore")
+
+    open_token: str = ""
+    openrouter_api_key: str = ""
+
+
+class ConfigManager:
+    def __init__(self) -> None:
+        self._env = _EnvSettings()
+        self._file_config: dict = self._load_file()
+
+    def _load_file(self) -> dict:
+        if not CONFIG_FILE.exists():
+            return {}
+        try:
+            with CONFIG_FILE.open("rb") as f:
+                return tomllib.load(f)
+        except Exception:
+            return {}
+
+    def resolve_token(self) -> str:
+        token = (
+            self._env.open_token
+            or self._env.openrouter_api_key
+            or self._file_config.get("api_key", "")
+        )
+        if not token:
+            raise AuthError(
+                "No API key found.\n\n"
+                "  Set env:   export OPEN_TOKEN=sk-or-xxx\n"
+                "  Or run:    hitmos login"
+            )
+        return token
+
+    def get_model(self) -> str:
+        return self._file_config.get("model", DEFAULT_MODEL)
+
+    def save_token(self, token: str) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        data = self._load_file()
+        data["api_key"] = token
+        self._write_file(data)
+
+    def save_model(self, model: str) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        data = self._load_file()
+        data["model"] = model
+        self._write_file(data)
+
+    def _write_file(self, data: dict) -> None:
+        lines = []
+        for key, value in data.items():
+            if isinstance(value, str):
+                lines.append(f'{key} = "{value}"')
+            else:
+                lines.append(f"{key} = {value}")
+        CONFIG_FILE.write_text("\n".join(lines) + "\n")

hitmos/constants.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+
+VERSION = "0.1.0"
+APP_NAME = "hitmos"
+APP_TITLE = "Hitmos"
+
+OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+OPENROUTER_CHAT_URL = f"{OPENROUTER_BASE_URL}/chat/completions"
+HTTP_REFERER = "https://github.com/ndugram/hitmos"
+
+DEFAULT_MODEL = "deepseek/deepseek-chat"
+
+CONFIG_DIR = Path.home() / ".hitmos"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+SYSTEM_PROMPT = (
+    "You are Hitmos, a helpful AI coding assistant. "
+    "Be concise, accurate, and developer-focused."
+)
+
+COMMANDS: dict[str, str] = {
+    "/help": "Show available commands",
+    "/clear": "Clear conversation history",
+    "/reset": "Reset context",
+    "/model": "Switch AI model (interactive picker)",
+    "/model <name>": "Switch AI model directly",
+    "/exit": "Exit Hitmos",
+}
+
+AVAILABLE_MODELS: list[tuple[str, str]] = [
+    ("deepseek/deepseek-chat",                  "DeepSeek Chat · fast, cheap, great for code"),
+    ("deepseek/deepseek-r1",                    "DeepSeek R1 · reasoning model"),
+    ("google/gemini-2.5-flash",                 "Gemini 2.5 Flash · fast multimodal"),
+    ("google/gemini-2.5-pro",                   "Gemini 2.5 Pro · powerful multimodal"),
+    ("anthropic/claude-3.5-haiku",              "Claude 3.5 Haiku · fast Anthropic"),
+    ("anthropic/claude-sonnet-4-5",             "Claude Sonnet 4.5 · balanced Anthropic"),
+    ("openai/gpt-4o-mini",                      "GPT-4o Mini · OpenAI fast"),
+    ("openai/o4-mini",                          "o4-mini · OpenAI reasoning"),
+    ("meta-llama/llama-3.3-70b-instruct",       "Llama 3.3 70B · open source"),
+    ("mistralai/mistral-small-3.2-24b-instruct","Mistral Small 3.2 · lightweight"),
+]

hitmos/context.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class ProjectContext:
+    _IGNORE_DIRS = frozenset({
+        ".git", "__pycache__", ".venv", "venv", "env",
+        "node_modules", "dist", "build", ".pytest_cache",
+        ".mypy_cache", ".ruff_cache", "eggs", ".eggs",
+        ".tox", "htmlcov", ".idea", ".vscode",
+    })
+    _IGNORE_EXTS = frozenset({
+        ".pyc", ".pyo", ".pyd", ".so", ".dylib", ".dll",
+        ".jpg", ".jpeg", ".png", ".gif", ".ico", ".svg", ".webp",
+        ".pdf", ".zip", ".tar", ".gz", ".bz2", ".whl", ".egg",
+        ".db", ".sqlite", ".sqlite3", ".bin", ".pkl",
+    })
+    _PRIORITY_NAMES = frozenset({
+        "README.md", "README.rst", "README.txt",
+        "pyproject.toml", "package.json", "Cargo.toml",
+        "setup.py", "setup.cfg", "requirements.txt",
+        "Makefile", "docker-compose.yml", "Dockerfile",
+        ".env.example",
+    })
+    MAX_FILE_BYTES = 25_000
+    MAX_TOTAL_BYTES = 120_000
+
+    def __init__(self, cwd: Path) -> None:
+        self.cwd = cwd
+
+    def build(self) -> tuple[str, int]:
+        """Returns (context_string, size_in_kb)."""
+        parts: list[str] = []
+
+        tree = self._tree()
+        if tree:
+            parts.append(f"Project structure ({self.cwd}):\n{tree}")
+
+        total = sum(len(p) for p in parts)
+        for path in self._collect():
+            if total >= self.MAX_TOTAL_BYTES:
+                parts.append("(context limit reached — more files exist)")
+                break
+            text = self._read(path)
+            if text is None:
+                continue
+            rel = str(path.relative_to(self.cwd))
+            block = f"--- {rel} ---\n{text}"
+            parts.append(block)
+            total += len(block)
+
+        context = "\n\n".join(parts)
+        return context, len(context) // 1024
+
+    def _tree(self) -> str:
+        lines: list[str] = []
+        self._walk_tree(self.cwd, "", lines, 0)
+        return "\n".join(lines)
+
+    def _walk_tree(self, path: Path, prefix: str, lines: list[str], depth: int) -> None:
+        if depth > 4:
+            return
+        try:
+            children = sorted(
+                [p for p in path.iterdir() if self._visible(p)],
+                key=lambda p: (p.is_file(), p.name.lower()),
+            )
+        except PermissionError:
+            return
+        for i, child in enumerate(children):
+            is_last = i == len(children) - 1
+            lines.append(f"{prefix}{'└── ' if is_last else '├── '}{child.name}")
+            if child.is_dir():
+                self._walk_tree(child, prefix + ("    " if is_last else "│   "), lines, depth + 1)
+
+    def _visible(self, path: Path) -> bool:
+        name = path.name
+        if name.startswith(".") and name not in {".env.example"}:
+            return False
+        if path.is_dir() and name in self._IGNORE_DIRS:
+            return False
+        if path.is_file() and path.suffix in self._IGNORE_EXTS:
+            return False
+        return True
+
+    def _collect(self) -> list[Path]:
+        priority: list[Path] = []
+        others: list[Path] = []
+        for path in self._rglob():
+            (priority if path.name in self._PRIORITY_NAMES else others).append(path)
+        return priority + sorted(others, key=lambda p: str(p))
+
+    def _rglob(self) -> list[Path]:
+        result: list[Path] = []
+        for path in self.cwd.rglob("*"):
+            if not path.is_file():
+                continue
+            rel_parts = path.relative_to(self.cwd).parts
+            if any(
+                p in self._IGNORE_DIRS or (p.startswith(".") and p != ".env.example")
+                for p in rel_parts[:-1]
+            ):
+                continue
+            if path.suffix in self._IGNORE_EXTS:
+                continue
+            result.append(path)
+        return result
+
+    def _read(self, path: Path) -> str | None:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+            if not text.strip():
+                return None
+            if len(text) > self.MAX_FILE_BYTES:
+                text = text[: self.MAX_FILE_BYTES] + "\n... (truncated)"
+            return text
+        except Exception:
+            return None

hitmos/exceptions.py

@@ -0,0 +1,22 @@
+class HitmosError(Exception):
+    """Base exception."""
+
+
+class AuthError(HitmosError):
+    """Invalid or missing API key."""
+
+
+class NetworkError(HitmosError):
+    """Network connectivity issue."""
+
+
+class APIError(HitmosError):
+    """API returned an error."""
+
+
+class RateLimitError(APIError):
+    """Rate limit exceeded."""
+
+
+class ConfigError(HitmosError):
+    """Configuration error."""

hitmos/methods/__init__.py

@@ -0,0 +1,45 @@
+import orjson
+
+from .base import BaseMethod, _snake
+from .edit_file import EditFile
+from .list_directory import ListDirectory
+from .read_file import ReadFile
+from .run_command import RunCommand
+from .write_file import WriteFile
+
+ALL_METHODS: list[type[BaseMethod]] = [
+    WriteFile,
+    ReadFile,
+    EditFile,
+    ListDirectory,
+    RunCommand,
+]
+
+ALL_TOOLS: list[dict] = [m.as_tool() for m in ALL_METHODS]
+
+_METHOD_MAP: dict[str, type[BaseMethod]] = {
+    _snake(m.__name__): m for m in ALL_METHODS
+}
+
+
+def dispatch(name: str, arguments: str | dict) -> str:
+    """Parse arguments and execute the named method."""
+    cls = _METHOD_MAP.get(name)
+    if cls is None:
+        return f"Unknown method: {name}"
+    if isinstance(arguments, str):
+        arguments = orjson.loads(arguments)
+    return cls.model_validate(arguments).call()
+
+
+__all__ = [
+    "BaseMethod",
+    "WriteFile",
+    "ReadFile",
+    "EditFile",
+    "ListDirectory",
+    "RunCommand",
+    "ALL_METHODS",
+    "ALL_TOOLS",
+    "dispatch",
+]

hitmos/methods/base.py

@@ -0,0 +1,33 @@
+import re
+from abc import abstractmethod
+
+from pydantic import BaseModel
+
+
+def _snake(name: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+
+class BaseMethod(BaseModel):
+    @abstractmethod
+    def call(self) -> str: ...
+
+    @classmethod
+    def as_tool(cls) -> dict:
+        schema = cls.model_json_schema()
+        params = {
+            "type": "object",
+            "properties": {
+                k: {kk: vv for kk, vv in v.items() if kk != "title"}
+                for k, v in schema.get("properties", {}).items()
+            },
+            "required": schema.get("required", []),
+        }
+        return {
+            "type": "function",
+            "function": {
+                "name": _snake(cls.__name__),
+                "description": (cls.__doc__ or "").strip(),
+                "parameters": params,
+            },
+        }

hitmos/methods/edit_file.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+from pydantic import Field
+
+from .base import BaseMethod
+
+
+class EditFile(BaseMethod):
+    """Replace the first occurrence of old_string with new_string in a file."""
+
+    path: str = Field(description="File path to edit")
+    old_string: str = Field(description="Exact string to find and replace")
+    new_string: str = Field(description="Replacement string")
+
+    def call(self) -> str:
+        p = Path(self.path)
+        if not p.exists():
+            return f"File not found: {self.path}"
+        text = p.read_text(encoding="utf-8")
+        if self.old_string not in text:
+            return f"String not found in {self.path}"
+        p.write_text(text.replace(self.old_string, self.new_string, 1), encoding="utf-8")
+        return f"Edited {self.path}"

hitmos/methods/list_directory.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+from pydantic import Field
+
+from .base import BaseMethod
+
+
+class ListDirectory(BaseMethod):
+    """List files and subdirectories at the given path."""
+
+    path: str = Field(default=".", description="Directory path (default: current directory)")
+
+    def call(self) -> str:
+        p = Path(self.path)
+        if not p.exists():
+            return f"Path not found: {self.path}"
+        items = sorted(p.iterdir(), key=lambda x: (not x.is_dir(), x.name))
+        if not items:
+            return "(empty)"
+        return "\n".join(f"{'dir ' if x.is_dir() else 'file'} {x.name}" for x in items)

hitmos/methods/read_file.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+
+from pydantic import Field
+
+from .base import BaseMethod
+
+
+class ReadFile(BaseMethod):
+    """Read the full contents of a file."""
+
+    path: str = Field(description="File path to read")
+
+    def call(self) -> str:
+        p = Path(self.path)
+        if not p.exists():
+            return f"File not found: {self.path}"
+        return p.read_text(encoding="utf-8")

hitmos/methods/run_command.py

@@ -0,0 +1,31 @@
+import subprocess
+
+from pydantic import Field
+
+from .base import BaseMethod
+
+
+class RunCommand(BaseMethod):
+    """Run a shell command and return its output."""
+
+    command: str = Field(description="Shell command to execute")
+    timeout: int = Field(default=30, description="Timeout in seconds")
+
+    def call(self) -> str:
+        try:
+            result = subprocess.run(
+                self.command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+            )
+            out = result.stdout.strip()
+            err = result.stderr.strip()
+            if result.returncode != 0:
+                return f"Exit {result.returncode}\n{err or out}"
+            return out or "(no output)"
+        except subprocess.TimeoutExpired:
+            return f"Command timed out after {self.timeout}s"
+        except Exception as e:
+            return f"Error: {e}"

hitmos/methods/write_file.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+from pydantic import Field
+
+from .base import BaseMethod
+
+
+class WriteFile(BaseMethod):
+    """Create or overwrite a file with the given content."""
+
+    path: str = Field(description="File path (relative to cwd or absolute)")
+    content: str = Field(description="Full file content to write")
+
+    def call(self) -> str:
+        p = Path(self.path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(self.content, encoding="utf-8")
+        return f"Written {len(self.content)} chars to {self.path}"

hitmos/ui.py

@@ -0,0 +1,217 @@
+import asyncio
+from collections.abc import AsyncGenerator
+
+import orjson
+import questionary
+from prompt_toolkit import PromptSession
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.formatted_text import FormattedText
+from prompt_toolkit.styles import Style as PTStyle
+from questionary import Style as QStyle
+from rich.console import Console
+from rich.live import Live
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .constants import APP_TITLE, AVAILABLE_MODELS, COMMANDS
+from .utils import get_cwd_display
+
+# ── questionary picker style ──────────────────────────────────────────────────
+_PICKER_STYLE = QStyle([
+    ("qmark",        "fg:#888888"),
+    ("question",     "fg:#888888"),
+    ("answer",       "fg:#00d7af bold"),
+    ("pointer",      "fg:#00d7af bold"),
+    ("highlighted",  "fg:#00d7af"),
+    ("selected",     "fg:#00d7af"),
+    ("separator",    "fg:#444444"),
+    ("instruction",  "fg:#444444"),
+    ("text",         ""),
+])
+
+# ── prompt input style ────────────────────────────────────────────────────────
+_INPUT_STYLE = PTStyle.from_dict({
+    "prompt":                               "bold",
+    "completion-menu.completion":           "bg:#1e1e1e #888888",
+    "completion-menu.completion.current":   "bg:#00d7af #000000 bold",
+    "completion-menu.meta.completion":      "bg:#1a1a1a #555555",
+    "completion-menu.meta.completion.current": "bg:#00875f #000000",
+    "scrollbar.background":                 "bg:#2a2a2a",
+    "scrollbar.button":                     "bg:#555555",
+})
+
+_COMMAND_COMPLETIONS = ["/help", "/clear", "/reset", "/model", "/exit"]
+
+
+class _HitmosCompleter(Completer):
+    def get_completions(self, document, complete_event):
+        text = document.text_before_cursor
+
+        if text.lower().startswith("/model "):
+            typed = text[7:]
+            for model_id, desc in AVAILABLE_MODELS:
+                if model_id.startswith(typed):
+                    yield Completion(
+                        model_id,
+                        start_position=-len(typed),
+                        display=model_id,
+                        display_meta=desc,
+                    )
+
+        elif text.startswith("/") and " " not in text:
+            for cmd in _COMMAND_COMPLETIONS:
+                if cmd.startswith(text):
+                    yield Completion(cmd, start_position=-len(text))
+
+
+class ConsoleUI:
+    def __init__(self) -> None:
+        self.console = Console(highlight=False)
+        self._session: PromptSession = PromptSession(
+            completer=_HitmosCompleter(),
+            complete_while_typing=False,
+            style=_INPUT_STYLE,
+        )
+
+    def show_welcome(self, model: str, ctx_kb: int = 0) -> None:
+        self.console.print()
+        self.console.print(
+            Panel(
+                Text.from_markup(
+                    f"[bold]✻  Welcome to {APP_TITLE}[/bold]\n\n"
+                    "[dim]/help for commands[/dim]"
+                ),
+                border_style="dim",
+                padding=(1, 2),
+            )
+        )
+        self.console.print()
+        self.console.print(f" [dim]◆[/dim] [dim]{get_cwd_display()}[/dim]")
+        self.console.print(f" [dim]◆[/dim] [dim]{model}[/dim]")
+        if ctx_kb > 0:
+            self.console.print(f" [dim]◆[/dim] [dim]context {ctx_kb} KB[/dim]")
+        self.console.print()
+
+    def show_help(self) -> None:
+        table = Table(show_header=False, box=None, padding=(0, 2, 0, 0))
+        table.add_column(style="bold cyan", no_wrap=True)
+        table.add_column(style="dim")
+        for cmd, desc in COMMANDS.items():
+            table.add_row(cmd, desc)
+        self.console.print()
+        self.console.print(table)
+        self.console.print()
+
+    async def show_model_picker(self, current: str) -> str | None:
+        self.console.print()
+
+        choices = [
+            questionary.Choice(
+                title=f"{model_id:<48} {desc}",
+                value=model_id,
+            )
+            for model_id, desc in AVAILABLE_MODELS
+        ]
+
+        default = next((c for c in choices if c.value == current), choices[0])
+
+        try:
+            result = await questionary.select(
+                "Select model  (↑↓ navigate, Enter confirm, Ctrl+C cancel)",
+                choices=choices,
+                default=default,
+                style=_PICKER_STYLE,
+                use_shortcuts=False,
+                use_arrow_keys=True,
+            ).ask_async()
+        except KeyboardInterrupt:
+            result = None
+
+        self.console.print()
+        return result
+
+    def show_error(self, message: str) -> None:
+        self.console.print()
+        lines = message.split("\n")
+        self.console.print(f" [bold red]✖[/bold red] {lines[0]}")
+        for line in lines[1:]:
+            if line:
+                self.console.print(f"   {line}")
+        self.console.print()
+
+    def show_info(self, message: str) -> None:
+        self.console.print()
+        self.console.print(f" [dim]{message}[/dim]")
+        self.console.print()
+
+    def show_success(self, message: str) -> None:
+        self.console.print()
+        self.console.print(f" [bold green]✓[/bold green] {message}")
+        self.console.print()
+
+    async def stream_response(self, token_gen: AsyncGenerator[str, None]) -> str:
+        self.console.print()
+        buffer = ""
+
+        async for first in token_gen:
+            buffer = first
+            break
+        else:
+            return buffer
+
+        MAX_CHARS = 24_000
+        truncated = False
+        interrupted = False
+
+        with Live(
+            Markdown(buffer),
+            console=self.console,
+            refresh_per_second=15,
+            vertical_overflow="visible",
+        ) as live:
+            try:
+                async for token in token_gen:
+                    buffer += token
+                    live.update(Markdown(buffer))
+                    if len(buffer) >= MAX_CHARS:
+                        truncated = True
+                        break
+            except (KeyboardInterrupt, asyncio.CancelledError):
+                interrupted = True
+            finally:
+                await token_gen.aclose()
+
+        if truncated:
+            self.console.print()
+            self.console.print(" [dim]Response truncated.[/dim]")
+        self.console.print()
+        if interrupted:
+            self.console.print(" [dim]Interrupted.[/dim]")
+            self.console.print()
+        return buffer
+
+    async def get_input(self) -> str:
+        return await self._session.prompt_async(
+            FormattedText([("class:prompt", "> ")]),
+        )
+
+    def show_tool_call(self, name: str, arguments: str) -> None:
+        try:
+            args = orjson.loads(arguments)
+            summary = "  ".join(f"[dim]{k}[/dim] {str(v)[:60]}" for k, v in args.items())
+        except Exception:
+            summary = arguments[:80]
+        self.console.print(f" [bold cyan]⚙[/bold cyan]  [cyan]{name}[/cyan]  {summary}")
+
+    def show_tool_result(self, result: str) -> None:
+        first_line = result.split("\n")[0]
+        preview = first_line[:80] + ("…" if len(result) > 80 else "")
+        self.console.print(f"   [dim]→ {preview}[/dim]")
+        self.console.print()
+
+    def show_exit(self) -> None:
+        self.console.print()
+        self.console.print(" [dim]Goodbye.[/dim]")
+        self.console.print()

hitmos/utils.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+
+def get_cwd_display() -> str:
+    cwd = Path.cwd()
+    try:
+        rel = cwd.relative_to(Path.home())
+        return f"~/{rel}" if str(rel) != "." else "~"
+    except ValueError:
+        return str(cwd)

hitmos-0.0.1.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: hitmos
+Version: 0.0.1
+Summary: AI terminal assistant powered by OpenRouter — minimal, fast, developer UX
+Project-URL: Homepage, https://github.com/ndugram/hitmos
+Project-URL: Documentation, https://github.com/ndugram/hitmos
+Project-URL: Repository, https://github.com/ndugram/hitmos
+Project-URL: Issues, https://github.com/ndugram/hitmos/issues
+Author-email: White NEFOR <n7for8572@gmail.com>
+Maintainer-email: White NEFOR <n7for8572@gmail.com>
+License: MIT
+Keywords: ai,assistant,chat,cli,deepseek,developer-tools,llm,openrouter,python,terminal
+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.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: fasthttp-client>=1.3.13
+Requires-Dist: orjson>=3.9.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.26.7
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ndugram/hitmos/master/docs/logo.png" style="background:white; padding:12px; border-radius:10px; width:300">
+</p>
+<p align="center">
+    <em>AI terminal assistant powered by OpenRouter — minimal, fast, developer UX.</em>
+</p>
+<p align="center">
+<a href="https://pypi.org/project/hitmos" target="_blank">
+    <img src="https://img.shields.io/pypi/v/hitmos?color=%2300d7af&label=pypi%20package" alt="Package version">
+</a>
+<a href="https://pypi.org/project/hitmos" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/hitmos.svg?color=%2300d7af" alt="Supported Python versions">
+</a>
+<a href="https://pypi.org/project/hitmos" target="_blank">
+    <img src="https://img.shields.io/pypi/dm/hitmos?color=%2300d7af&label=downloads" alt="Monthly downloads">
+</a>
+<a href="https://pepy.tech/projects/hitmos" target="_blank">
+    <img src="https://img.shields.io/pepy/dt/hitmos?color=%2300d7af&label=total%20downloads" alt="Total downloads">
+</a>
+<a href="https://github.com/ndugram/hitmos" target="_blank">
+    <img src="https://img.shields.io/github/stars/ndugram/hitmos?style=social" alt="GitHub Stars">
+</a>
+</p>
+
+---
+
+**Source Code**: <a href="https://github.com/ndugram/hitmos" target="_blank">https://github.com/ndugram/hitmos</a>
+
+---
+
+Hitmos is a modern **AI terminal assistant** for developers, powered by <a href="https://openrouter.ai" target="_blank">OpenRouter</a>. It brings a Claude Code–styled UX to your terminal — live markdown streaming, interactive model switching, project context injection, and Tab completion, all with zero latency overhead.
+
+Key features:
+
+- **Streaming** — responses stream token-by-token with live Markdown rendering via <a href="https://github.com/Textualize/rich" target="_blank">rich</a>.
+- **Multi-model** — switch between DeepSeek, Gemini, Claude, GPT-4o, Llama, and more with an interactive arrow-key picker.
+- **Project context** — automatically injects your project files into the system prompt so the model can answer project-specific questions.
+- **Tab completion** — `/model <Tab>` lists all available models; `/` completes all commands.
+- **Minimal UX** — Claude Code–inspired welcome panel, `◆` status lines, clean `>` prompt.
+- **Fast** — built on <a href="https://github.com/ndugram/fasthttp" target="_blank">fasthttp-client</a> with full async SSE streaming.
+- **Configurable** — API key via env (`OPEN_TOKEN`, `OPENROUTER_API_KEY`) or `~/.hitmos/config.toml`.
+
+## Requirements
+
+Python 3.13+
+
+Hitmos depends on:
+
+- <a href="https://github.com/ndugram/fasthttp" target="_blank"><code>fasthttp-client</code></a> — async HTTP transport with SSE streaming.
+- <a href="https://github.com/Textualize/rich" target="_blank"><code>rich</code></a> — live Markdown rendering and styled console output.
+- <a href="https://typer.tiangolo.com/" target="_blank"><code>typer</code></a> — CLI interface.
+- <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> — fast JSON parsing.
+- <a href="https://github.com/prompt-toolkit/python-prompt-toolkit" target="_blank"><code>prompt-toolkit</code></a> — async input with Tab completion (bundled with questionary).
+- <a href="https://github.com/tmbo/questionary" target="_blank"><code>questionary</code></a> — interactive model picker.
+- <a href="https://docs.pydantic.dev/" target="_blank"><code>pydantic-settings</code></a> — config management.
+
+## Installation
+
+```console
+$ pip install hitmos
+
+---> 100%
+```
+
+## Quickstart
+
+### Save your API key
+
+```console
+$ hitmos login
+```
+
+Or set an environment variable:
+
+```console
+$ export OPEN_TOKEN=sk-or-...
+```
+
+### Start chatting
+
+```console
+$ hitmos
+```
+
+You will see:
+
+```
+╭─────────────────────────────────────────────────────╮
+│                                                     │
+│  ✻  Welcome to Hitmos                               │
+│                                                     │
+│  /help for commands                                 │
+│                                                     │
+╰─────────────────────────────────────────────────────╯
+
+ ◆ ~/my-project
+ ◆ deepseek/deepseek-chat
+ ◆ context 12 KB
+
+>
+```
+
+Ask anything about your project:
+
+```
+> what does this project do?
+> add error handling to client.py
+> explain the streaming logic
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/help` | Show available commands |
+| `/model` | Interactive model picker (↑↓ + Enter) |
+| `/model <name>` | Switch model directly |
+| `/clear` | Clear conversation history |
+| `/reset` | Reset context |
+| `/exit` | Exit Hitmos |
+
+### Switch model interactively
+
+Type `/model` and press Enter to open the arrow-key picker:
+
+```
+? Select model  (↑↓ navigate, Enter confirm, Ctrl+C cancel)
+❯ deepseek/deepseek-chat                   DeepSeek Chat · fast, cheap, great for code
+  deepseek/deepseek-r1                     DeepSeek R1 · reasoning model
+  google/gemini-2.5-flash                  Gemini 2.5 Flash · fast multimodal
+  google/gemini-2.5-pro                    Gemini 2.5 Pro · powerful multimodal
+  anthropic/claude-3.5-haiku               Claude 3.5 Haiku · fast Anthropic
+  anthropic/claude-sonnet-4-5              Claude Sonnet 4.5 · balanced Anthropic
+  openai/gpt-4o-mini                       GPT-4o Mini · OpenAI fast
+  openai/o4-mini                           o4-mini · OpenAI reasoning
+  meta-llama/llama-3.3-70b-instruct        Llama 3.3 70B · open source
+  mistralai/mistral-small-3.2-24b-instruct Mistral Small 3.2 · lightweight
+```
+
+Or use Tab completion: type `/model deep` then press `Tab`.
+
+## Configuration
+
+Hitmos resolves the API key in this order:
+
+1. `OPEN_TOKEN` environment variable
+2. `OPENROUTER_API_KEY` environment variable
+3. `~/.hitmos/config.toml`
+
+Config file format:
+
+```toml
+token = "sk-or-..."
+model = "deepseek/deepseek-chat"
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request on <a href="https://github.com/ndugram/hitmos" target="_blank">GitHub</a>.
+
+## License
+
+This project is licensed under the terms of the <a href="https://github.com/ndugram/hitmos/blob/master/LICENSE" target="_blank">MIT license</a>.

hitmos-0.0.1.dist-info/RECORD

@@ -0,0 +1,23 @@
+hitmos/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+hitmos/app.py,sha256=QkNm0M7yirdmlu_fcxFslOaOJtvuE3qIsgEBOH2IaXQ,5730
+hitmos/chat.py,sha256=w4xsAEB-ZwuhGKeoRE1fXFpIuvJcl4VvTD3gDO6RYYM,977
+hitmos/cli.py,sha256=oJIPN6CgxchZs4OEmyXIiAUyfpNW1RACbVXgr84icBg,1126
+hitmos/client.py,sha256=o2926AoPE6INGCyEy-OAus36Wgk5OaaCNqAMJCbmnoU,4399
+hitmos/commands.py,sha256=X9fQmBUcc8wYQHLwALhE-ailWRjj8Mf-MACYunB63vg,910
+hitmos/config.py,sha256=fbRy_HvGdHb7K3JZ61haBfSMZkxxiS7O3q8NdTEPQCw,1961
+hitmos/constants.py,sha256=XirbJf-tlXErx3UV6uyUCDDBUzsQ7Hwv6DfKXQOnMaw,1688
+hitmos/context.py,sha256=6_Mkq65K1eEJ3H1f59PUvetWmfYLcCYuqxE_F9ZHG8I,4203
+hitmos/exceptions.py,sha256=1PRjXeX4_QoTetYEyOojehkOvBhP9E40ghSmT5YmS4Y,393
+hitmos/ui.py,sha256=Mk-_ky3mW-Ut9Vyo-tHrqLbc7orPeki1BnLxBQW_4Cw,7672
+hitmos/utils.py,sha256=tFHXLk-1TezhWiPQoNEdV_Ng1AxaeL6_Y5lyRhFB2QQ,231
+hitmos/methods/__init__.py,sha256=ZC1vMjNZ8Wxu578ztwt1RmrlLnpGbWDObN2kSYs4WVA,1011
+hitmos/methods/base.py,sha256=lBPcLQeWZjyE9N5qTGScj5GCh8F48ziasC-MEPXtXPY,865
+hitmos/methods/edit_file.py,sha256=WcowNwSrqujPQekSRix43AgljYbtB1FuoxvJmZ3qXhw,786
+hitmos/methods/list_directory.py,sha256=UEaDLrfy-ibArdgDz0l12jg0-4e1FYGKgakMqXMl5eQ,620
+hitmos/methods/read_file.py,sha256=p-pi8ukMSMfC7yCFq1N5thRTtz7kVOQn_GRwz9zbfCc,391
+hitmos/methods/run_command.py,sha256=mbiDkQDOjxlGWJv2sgqHJBMOwc_mLFJrfK04YEQtuWI,942
+hitmos/methods/write_file.py,sha256=ntxW5453n4CP4ck9GJx_1zFC7dX0UNeS2cPrQ2f6XLI,548
+hitmos-0.0.1.dist-info/METADATA,sha256=OakZJEhhEQ4cmeyxMG-mw3g8Va1INXP3SkT4QNfP1UY,7845
+hitmos-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hitmos-0.0.1.dist-info/entry_points.txt,sha256=NWubdQwXCRS7hB_tdxuYxCchPl7A_OoT7x14EO76mQo,42
+hitmos-0.0.1.dist-info/RECORD,,

hitmos-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

hitmos-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hitmos = hitmos.cli:app