agentkernel-cli 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

agentkernel/agent.py

@@ -67,13 +67,15 @@ class Agent:
         *,
         profile: Any | None = None,
         on_text: Any | None = None,
+        images: Any | None = None,
     ) -> str:
         """Drive the loop until a final answer or the max-iteration guard.
 
         ``profile`` (design §13, Phase 5) is accepted but, in the kernel, only
         ``tool_filter`` / ``system_prompt`` are honored if trivially present.
         ``on_text`` (when set) receives streamed text deltas; the loop contract is
-        otherwise unchanged.
+        otherwise unchanged. ``images`` (a list of ``ImageContent``) attaches to
+        the user turn; adapters that can't accept images ignore them (§18.6).
         """
         session_id = getattr(self.telemetry, "session_id", str(uuid.uuid4()))
 
@@ -84,7 +86,11 @@ class Agent:
                 self.context.add(message)
 
         self.context.add(
-            Message(role="user", content=self._prepare_user_message(user_input))
+            Message(
+                role="user",
+                content=self._prepare_user_message(user_input),
+                images=list(images) if images else [],
+            )
         )
 
         # Assemble the cacheable prefix ONCE per run and reuse the same objects

agentkernel/cli.py

@@ -20,7 +20,6 @@ import fnmatch
 import json
 import sys
 from collections.abc import Callable
-from dataclasses import replace
 from pathlib import Path
 
 from agentkernel.agent import Agent
@@ -35,6 +34,7 @@ from agentkernel.mcp.config import MCPServerConfig
 from agentkernel.memory import (
     MemoryStore,
     NoteStore,
+    RecallWeighting,
     make_memory_store,
     make_memory_tools,
     make_note_store,
@@ -43,16 +43,19 @@ from agentkernel.paths import agent_home, global_config_path
 from agentkernel.profiles import Profile, load_profile
 from agentkernel.progress import ProgressTelemetry
 from agentkernel.providers import ProviderError, make_provider
+from agentkernel.roles import provider_for_role, provider_with_model
 from agentkernel.semantic_memory import SemanticSqliteNoteStore
 from agentkernel.skills import DirectorySkillStore, make_skill_tool
 from agentkernel.subagent import make_spawn_tool
 from agentkernel.telemetry import JsonlTelemetry, NullTelemetry
 from agentkernel.tools import ToolRegistry
 from agentkernel.tools.builtin import default_tools
+from agentkernel.types import ImageContent
 
 _BANNER = (
     "agentkernel REPL - type your message and press enter. Commands: /exit, "
-    "/clear, /system, /profile, /skills, /skill, /tools, /trace, /cost, /memory, /improve."
+    "/clear, /image, /system, /profile, /skills, /skill, /tools, /trace, /cost, "
+    "/memory, /improve."
 )
 _PROMPT = "> "
 _EXIT_WORDS = {"exit", "quit", ":q"}
@@ -64,6 +67,12 @@ def _make_configured_note_store(config: Config) -> NoteStore:
     Shared by build_runtime (memory tools) and run_memory (curation), so the
     notebook backend is selected identically in both.
     """
+    weighting = RecallWeighting(
+        recency_weight=config.memory_recency_weight,
+        importance_weight=config.memory_importance_weight,
+        half_life_days=config.memory_half_life_days,
+    )
+    scope = _resolve_memory_scope(config)
     if config.semantic_search:
         try:
             emb_provider = OpenAIEmbeddingProvider.from_config(config)
@@ -74,10 +83,26 @@ def _make_configured_note_store(config: Config) -> NoteStore:
                 notes_path,
                 embedding_provider=emb_provider,
                 lsh_bits=config.semantic_search_lsh_bits,
+                weighting=weighting,
+                scope=scope,
             )
         except EmbeddingError as exc:
             print(f"Warning: semantic search disabled: {exc}", file=sys.stderr)
-    return make_note_store(config.memory_notes_path)
+    return make_note_store(config.memory_notes_path, weighting=weighting, scope=scope)
+
+
+def _resolve_memory_scope(config: Config) -> str | None:
+    """Resolve ``config.memory_scope`` to the active namespace (or ``None`` = off).
+
+    ``"auto"`` derives a stable name from the project directory; an empty value
+    disables scoping; any other string is used literally.
+    """
+    raw = (config.memory_scope or "").strip()
+    if not raw:
+        return None
+    if raw.lower() == "auto":
+        return Path(config.working_dir or ".").resolve().name or None
+    return raw
 
 
 def build_runtime(
@@ -189,9 +214,7 @@ def build_runtime(
     budget_for_context = provider.context_window - config.output_reserve
     summarizer = None
     if config.summarizer_model:
-        summarizer = ModelSummarizer(
-            make_provider(replace(config, model=config.summarizer_model))
-        )
+        summarizer = ModelSummarizer(provider_for_role(config, "summarize"))
     context = ContextManager(
         budget=budget_for_context,
         keep_recent_turns=config.keep_recent_turns,
@@ -202,8 +225,7 @@ def build_runtime(
     if config.approval_policy == "smart":
         from agentkernel.approval.risk import RiskJudge
 
-        judge_model = config.approval_judge_model or config.summarizer_model or config.model
-        risk_judge = RiskJudge(make_provider(replace(config, model=judge_model)))
+        risk_judge = RiskJudge(provider_for_role(config, "classify"))
     approver = CliApprover(
         config.approval_policy,
         allowlist=config.approval_allowlist,
@@ -265,6 +287,7 @@ def _handle_slash(
     profile: Profile,
     config: Config,
     output_fn: Callable[[str], None],
+    staged_images: list[ImageContent] | None = None,
 ) -> bool:
     """Process a REPL slash command. Returns True if the line was handled."""
     parts = line.split(None, 1)
@@ -279,6 +302,33 @@ def _handle_slash(
         output_fn("[context cleared]")
         return True
 
+    if cmd == "image":
+        target = arg.strip()
+        if not target or target == "list":
+            count = len(staged_images or [])
+            output_fn(
+                f"[{count} image(s) staged for the next message]"
+                if count
+                else "[no images staged] usage: /image <path-or-url> | /image clear"
+            )
+            return True
+        if target == "clear":
+            if staged_images is not None:
+                staged_images.clear()
+            output_fn("[staged images cleared]")
+            return True
+        try:
+            loaded = _load_images([target]) or []
+        except (OSError, ValueError) as exc:
+            output_fn(f"[image error] {exc}")
+            return True
+        if staged_images is not None:
+            staged_images.extend(loaded)
+        supported = getattr(agent._provider_for(profile), "supports_images", False)
+        warn = "" if supported else f"  (note: provider {config.provider!r} can't accept images)"
+        output_fn(f"[staged image: {target}]{warn}")
+        return True
+
     if cmd == "system":
         if not arg:
             output_fn("[system prompt cleared]")
@@ -435,6 +485,7 @@ def repl(
     streaming = stream_fn is not None and getattr(cfg, "stream", True)
     output_fn(_BANNER)
     profile = Profile(name="default")
+    staged_images: list[ImageContent] = []  # attached to the next message, then cleared
     while True:
         try:
             line = input_fn(_PROMPT).strip()
@@ -446,7 +497,7 @@ def repl(
         if line.lower() in _EXIT_WORDS:
             break
         if line.startswith("/"):
-            if not _handle_slash(line, agent, profile, cfg, output_fn):
+            if not _handle_slash(line, agent, profile, cfg, output_fn, staged_images):
                 break
             continue
         streamed = {"any": False}
@@ -455,13 +506,18 @@ def repl(
             _s["any"] = True
             stream_fn(text)  # type: ignore[misc]
 
+        images = list(staged_images) if staged_images else None
         try:
             answer = agent.run(
-                line, profile=profile, on_text=on_text if streaming else None
+                line,
+                profile=profile,
+                on_text=on_text if streaming else None,
+                images=images,
             )
         except ProviderError as exc:
             output_fn(f"[provider error] {exc}")
             continue
+        staged_images.clear()  # consumed by the message just sent
         if streaming and streamed["any"]:
             stream_fn("\n")  # type: ignore[misc]
         else:
@@ -469,6 +525,19 @@ def repl(
     return 0
 
 
+def _load_images(specs: list[str] | None) -> list[ImageContent] | None:
+    """Build ImageContent from --image specs (http(s) URL or local file path)."""
+    if not specs:
+        return None
+    images: list[ImageContent] = []
+    for spec in specs:
+        if spec.startswith(("http://", "https://")):
+            images.append(ImageContent.from_url(spec))
+        else:
+            images.append(ImageContent.from_path(spec))
+    return images
+
+
 def run_once(
     agent: Agent,
     prompt: str,
@@ -477,19 +546,29 @@ def run_once(
     output_fn: Callable[[str], None] = print,
     stream_fn: Callable[[str], None] | None = None,
     config: Config | None = None,
+    images: list[ImageContent] | None = None,
 ) -> int:
     """Execute a single non-interactive turn and print (or stream) the answer."""
     cfg = config or agent.config
     streaming = stream_fn is not None and getattr(cfg, "stream", True)
     streamed = {"any": False}
 
+    if images and not getattr(agent._provider_for(profile), "supports_images", False):
+        output_fn(
+            f"[warning] provider {cfg.provider!r} (model {cfg.model!r}) does not "
+            "accept images; sending text only"
+        )
+
     def on_text(text: str) -> None:
         streamed["any"] = True
         stream_fn(text)  # type: ignore[misc]
 
     try:
         answer = agent.run(
-            prompt, profile=profile, on_text=on_text if streaming else None
+            prompt,
+            profile=profile,
+            on_text=on_text if streaming else None,
+            images=images,
         )
     except ProviderError as exc:
         output_fn(f"[provider error] {exc}")
@@ -564,6 +643,106 @@ def run_new(
     return 0
 
 
+def run_completion(
+    shell: str, commands: list[str], *, output_fn: Callable[[str], None] = print
+) -> int:
+    """Print a shell completion script for ``agentkernel`` (§18.7).
+
+    Completes the subcommand at the first position and defers to file completion
+    afterwards. The command list is passed in from the live parser so the script
+    never drifts from the actual subcommands.
+    """
+    words = " ".join(commands)
+    if shell == "bash":
+        script = f"""\
+# agentkernel bash completion. Install:  source <(agentkernel completion bash)
+_agentkernel_completion() {{
+    local cur="${{COMP_WORDS[COMP_CWORD]}}"
+    if [ "$COMP_CWORD" -eq 1 ]; then
+        COMPREPLY=( $(compgen -W "{words}" -- "$cur") )
+    else
+        COMPREPLY=( $(compgen -f -- "$cur") )
+    fi
+}}
+complete -F _agentkernel_completion agentkernel
+"""
+    elif shell == "zsh":
+        script = f"""\
+#compdef agentkernel
+# agentkernel zsh completion. Install:  agentkernel completion zsh > ~/.zsh/_agentkernel
+_agentkernel() {{
+    local -a commands
+    commands=({words})
+    if (( CURRENT == 2 )); then
+        compadd -- $commands
+    else
+        _files
+    fi
+}}
+_agentkernel "$@"
+"""
+    elif shell == "fish":
+        lines = [
+            "# agentkernel fish completion. Install:  "
+            "agentkernel completion fish > ~/.config/fish/completions/agentkernel.fish",
+            f'complete -c agentkernel -n "__fish_use_subcommand" -a "{words}"',
+        ]
+        script = "\n".join(lines) + "\n"
+    else:
+        output_fn(f"[unsupported shell: {shell}] choose bash, zsh, or fish")
+        return 1
+    output_fn(script)
+    return 0
+
+
+def run_skill(
+    config: Config,
+    action: str,
+    target: str | None,
+    *,
+    out_path: str | None = None,
+    force: bool = False,
+    output_fn: Callable[[str], None] = print,
+) -> int:
+    """Manage shareable skill bundles: ``list`` / ``pack`` / ``install`` (§18.8)."""
+    from agentkernel.skills import SkillLibrary, install_skill, pack_skill
+
+    skills_dir = config.skills_dir
+    if action == "list":
+        library = SkillLibrary(skills_dir)
+        described = library.describe()
+        if not described:
+            output_fn(f"[no skills in {skills_dir}]")
+            return 0
+        for name, desc in described:
+            output_fn(f"- {name}: {desc}")
+        return 0
+    if action == "pack":
+        if not target:
+            output_fn("[pack] a skill name is required")
+            return 1
+        try:
+            archive = pack_skill(skills_dir, target, out_path=out_path)
+        except FileNotFoundError as exc:
+            output_fn(f"[pack] {exc}")
+            return 1
+        output_fn(f"[packed {target}: {archive}]")
+        return 0
+    if action == "install":
+        if not target:
+            output_fn("[install] an archive path is required")
+            return 1
+        try:
+            name = install_skill(target, skills_dir, force=force)
+        except (FileExistsError, ValueError, OSError) as exc:
+            output_fn(f"[install] {exc}")
+            return 1
+        output_fn(f"[installed skill {name!r} into {skills_dir}]")
+        return 0
+    output_fn(f"[unknown skill action: {action}] choose list, pack, or install")
+    return 1
+
+
 _PROJECT_CONFIG_TEMPLATE = """\
 # agentkernel project config. Global defaults live in ~/.agentkernel/config.toml
 # (or $AGENTKERNEL_HOME); keys here override them for this project.
@@ -882,8 +1061,7 @@ def run_memory(
     from agentkernel.curation import MemoryCurator
 
     notes = _make_configured_note_store(config)
-    curator_model = config.memory_curator_model or config.summarizer_model or config.model
-    provider = make_provider(replace(config, model=curator_model))
+    provider = provider_for_role(config, "curate")
     curator = MemoryCurator(notes, provider)
 
     if action == "consolidate":
@@ -1005,11 +1183,11 @@ def run_eval(
             context_source=base_agent.context_source,
         )
 
+    # An explicit --judge-model (or config.judge_model) overrides; otherwise reuse
+    # the agent's own provider rather than spinning up a duplicate.
     judge_model = judge_model or config.judge_model
     judge = (
-        make_provider(replace(config, model=judge_model))
-        if judge_model
-        else base_agent.provider
+        provider_with_model(config, judge_model) if judge_model else base_agent.provider
     )
     evaluator = Evaluator(
         agent_factory, judge,
@@ -1196,6 +1374,12 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="run detached in the background; output goes to a file",
     )
+    run_parser.add_argument(
+        "--image",
+        action="append",
+        metavar="PATH_OR_URL",
+        help="attach an image to the prompt (repeatable); a local path or http(s) URL",
+    )
     improve_parser = subparsers.add_parser(
         "improve", help="reflect on a session trace and write an improvement note"
     )
@@ -1291,6 +1475,25 @@ def main(argv: list[str] | None = None) -> int:
         "--force", action="store_true", help="overwrite if the target already exists"
     )
 
+    skill_parser = subparsers.add_parser(
+        "skill", help="package and install shareable skill bundles"
+    )
+    skill_parser.add_argument(
+        "skill_action", choices=("list", "pack", "install"), help="what to do"
+    )
+    skill_parser.add_argument(
+        "target", nargs="?", help="skill name (pack) or bundle path (install)"
+    )
+    skill_parser.add_argument("--out", help="output path for `pack` (.skill.zip)")
+    skill_parser.add_argument(
+        "--force", action="store_true", help="overwrite on `install`"
+    )
+
+    completion_parser = subparsers.add_parser(
+        "completion", help="print a shell completion script (bash/zsh/fish)"
+    )
+    completion_parser.add_argument("shell", choices=("bash", "zsh", "fish"))
+
     args = parser.parse_args(argv)
     command = getattr(args, "command", None) or "repl"
 
@@ -1306,6 +1509,8 @@ def main(argv: list[str] | None = None) -> int:
         )
     if command == "new":
         return run_new(args.kind, args.name, force=args.force)
+    if command == "completion":
+        return run_completion(args.shell, sorted(subparsers.choices))
 
     config, project_config_path = resolve_config(args.config, cwd=args.cwd or ".")
     # The concrete config path to hand to subprocesses / MCP discovery.
@@ -1334,6 +1539,14 @@ def main(argv: list[str] | None = None) -> int:
         return run_sessions(config, args.action, getattr(args, "session_id", None))
     if command == "memory":
         return run_memory(config, args.action, session=getattr(args, "session", None))
+    if command == "skill":
+        return run_skill(
+            config,
+            args.skill_action,
+            args.target,
+            out_path=getattr(args, "out", None),
+            force=getattr(args, "force", False),
+        )
     if command == "cron":
         return run_cron(config, args.action, args.rest)
     if command == "kanban":
@@ -1467,8 +1680,14 @@ def main(argv: list[str] | None = None) -> int:
             prompt = args.prompt
             if args.file:
                 prompt = _read_prompt_file(args.file)
+            images = _load_images(getattr(args, "image", None))
             return run_once(
-                agent, prompt or "", profile=profile, stream_fn=stream_fn, config=config
+                agent,
+                prompt or "",
+                profile=profile,
+                stream_fn=stream_fn,
+                config=config,
+                images=images,
             )
         return repl(agent, config=config, stream_fn=stream_fn)
     finally:

agentkernel/config.py

@@ -20,9 +20,10 @@ DEFAULT_CONFIG_FILE = "agentkernel.toml"
 
 @dataclass
 class Config:
-    provider: str = "anthropic"  # "anthropic" | "openai" | "local"
+    provider: str = "anthropic"  # anthropic|openai|local|openrouter|deepseek|gemini
     model: str = "claude-sonnet-4-6"
     base_url: str | None = None  # for local/OpenAI-compatible endpoints
+    local_supports_images: bool = False  # local endpoint accepts image_url parts (§18.6)
     max_output_tokens: int = 4096
     output_reserve: int = 8192  # budget headroom for the reply
     max_iterations: int = 25
@@ -62,6 +63,10 @@ class Config:
     memory_auto_context_limit: int = 3  # max notes per auto-recall
     memory_store_budget: int | None = None  # max tokens to persist per session
     memory_curator_model: str | None = None  # cheap model for memory extract/consolidate
+    memory_scope: str | None = None  # recall namespace: "auto" (project dir) | name | None=off
+    memory_recency_weight: float = 0.0  # boost recall of recently-created notes
+    memory_importance_weight: float = 0.0  # boost recall of often-recalled notes
+    memory_half_life_days: float = 30.0  # age (days) for a note's recency score to halve
     semantic_search: bool = False  # rank note recall with dense embeddings
     embedding_model: str = "text-embedding-3-small"
     embedding_dimensions: int | None = None  # optional truncation (OpenAI only)

agentkernel/context/manager.py

@@ -24,6 +24,11 @@ from agentkernel.types import Message
 if TYPE_CHECKING:
     from agentkernel.providers import Provider
 
+# Flat token charge per attached image (design §18.6). A rough upper-mid estimate
+# for a typical tiled image; cheaper than measuring the base64 payload and avoids
+# wildly over-counting an inline data URI.
+IMAGE_TOKEN_ESTIMATE = 1000
+
 # A summarizer turns a list of (old) messages into one summary string. The
 # default is the deterministic structural fallback below; a model-based
 # summarizer can be injected here (design §9.2).
@@ -40,13 +45,19 @@ class CompactionEvent:
 
 
 def estimate_tokens(message: Message) -> int:
-    """Conservative chars/4 estimate for one message (design §9.1)."""
+    """Conservative chars/4 estimate for one message (design §9.1).
+
+    Images are not text, so they are charged a flat per-image estimate rather
+    than by their (large) base64 length — close enough to keep the budget honest
+    without over-counting an inline data URI.
+    """
     chars = len(message.content or "")
     for tc in message.tool_calls:
         chars += len(tc.name) + len(json.dumps(tc.arguments))
     for r in message.tool_results:
         chars += len(r.content or "")
-    return max(1, chars // CHARS_PER_TOKEN)
+    image_tokens = len(message.images) * IMAGE_TOKEN_ESTIMATE
+    return max(1, chars // CHARS_PER_TOKEN + image_tokens)
 
 
 def structural_summary(messages: list[Message]) -> str:

agentkernel/curation.py

@@ -136,26 +136,59 @@ class MemoryCurator:
         existing = self._notes.all()
         if len(existing) < 2:
             return ConsolidationResult(len(existing), len(existing), existing)
+        # Consolidate within each namespace so distinct scopes are never merged
+        # together and every rebuilt note keeps its original scope. Without this,
+        # rebuilding via add() would re-stamp every note with the store's active
+        # scope, collapsing global and other-project notes into one namespace.
+        groups: dict[str, list[MemoryNote]] = {}
+        for note in existing:
+            groups.setdefault(note.scope, []).append(note)
+
+        new_notes: list[MemoryNote] = []
+        changed = False
+        for scope, group in groups.items():
+            rebuilt = self._consolidate_group(scope, group)
+            if rebuilt is None:  # no-op for this group (too small or unparseable)
+                new_notes.extend(group)
+            else:
+                new_notes.extend(rebuilt)
+                changed = True
+        if not changed:
+            return ConsolidationResult(len(existing), len(existing), existing)
+        return ConsolidationResult(len(existing), len(new_notes), new_notes)
+
+    def _consolidate_group(
+        self, scope: str, group: list[MemoryNote]
+    ) -> list[MemoryNote] | None:
+        """Consolidate one namespace's notes, preserving ``scope``.
+
+        Returns the rebuilt notes, or ``None`` to signal a no-op (fewer than two
+        notes, or an empty/unparseable model reply) so the caller keeps the
+        originals untouched.
+        """
+        if len(group) < 2:
+            return None
         listing = "\n".join(
             f"{n.note_id}. {n.text}"
             + (f"  [tags: {', '.join(n.tags)}]" if n.tags else "")
-            for n in existing
+            for n in group
         )
         cleaned = [
             c for c in self._ask(_CONSOLIDATE_SYSTEM, f"Current memory notes:\n{listing}")
             if str(c.get("text", "")).strip()
         ]
         if not cleaned:
-            return ConsolidationResult(len(existing), len(existing), existing)  # no-op
-        # Rebuild from the consolidated set using the store's public API so all
-        # backends (JSONL / SQLite / semantic) stay consistent.
-        for note in existing:
+            return None
+        # Rebuild this group using the store's public API (so all backends stay
+        # consistent), re-stamping each note with the group's original scope.
+        for note in group:
             self._notes.forget(note_id=note.note_id)
-        new_notes = [
-            self._notes.add(str(c["text"]).strip(), tags=c.get("tags") or [])
+        return [
+            self._notes.add(
+                str(c["text"]).strip(), tags=c.get("tags") or [], scope=scope
+            )
             for c in cleaned
         ]
-        return ConsolidationResult(len(existing), len(new_notes), new_notes)
 
     # --- internals ---------------------------------------------------------