atbots 0.1.0__py3-none-any.whl

atbots/__init__.py

@@ -0,0 +1,5 @@
+"""AtBot: local-first intelligence companion for AtMem authority."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

atbots/agent.py

@@ -0,0 +1,129 @@
+"""Bounded independent-agent loop driven by installed tools and skills."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+import uuid
+from typing import Any
+
+from atbots.capabilities import Hooks, Tool, ToolRegistry, guard_tool_result, load_skills
+from atbots.config import AtBotConfig
+from atbots.providers.router import ModelRouter
+from atbots.runtime import AtBotRuntime
+
+
+STEP_SCHEMA: dict[str, Any] = {
+    "title": "AtBotTaskStep",
+    "type": "object",
+    "required": ["action", "reason"],
+    "properties": {
+        "action": {"enum": ["tool", "finish"]},
+        "reason": {"type": "string"},
+        "tool": {"type": ["string", "null"]},
+        "arguments": {"type": "object"},
+        "answer": {"type": ["string", "null"]},
+    },
+}
+
+
+@dataclass(frozen=True, slots=True)
+class TaskResult:
+    run_id: str
+    answer: str
+    status: str
+    steps: int
+    trace: tuple[dict[str, object], ...]
+
+
+class TaskAgent:
+    def __init__(self, config: AtBotConfig, runtime: AtBotRuntime | None = None) -> None:
+        self.config = config
+        self.runtime = runtime or AtBotRuntime(config)
+        self.router = ModelRouter(config)
+        self.hooks = Hooks()
+        self.tools = ToolRegistry(config.allowed_tools)
+        self.tools.register(
+            Tool(
+                name="memory_recall",
+                description="Retrieve governed AtMem memories relevant to a query.",
+                input_schema={"type": "object", "required": ["query"], "properties": {"query": {"type": "string"}}},
+                handler=self._memory_recall,
+            )
+        )
+        self.skills = load_skills(config.skill_directories)
+
+    def _memory_recall(self, arguments: dict[str, Any]) -> object:
+        result = self.runtime.recall(str(arguments.get("query") or ""))
+        return [{"memory": row.content, "score": row.score} for row in result.candidates]
+
+    def run(self, objective: str, *, remote: bool = False) -> TaskResult:
+        if not objective.strip():
+            raise ValueError("objective is required")
+        run_id = uuid.uuid4().hex
+        provider = self.router.select(remote=remote)
+        observations: list[str] = []
+        trace: list[dict[str, object]] = []
+        skill_names = [skill.name for skill in self.skills]
+        self.hooks.emit("task.started", {"run_id": run_id, "tool_count": len(self.tools.descriptions())})
+        if "memory_recall" in self.tools.allowed:
+            # Memory is a governed input to every independent task, not an
+            # optional fact the planning model may guess about or skip.
+            value = self.tools.invoke("memory_recall", {"query": objective})
+            observation = guard_tool_result(value)
+            observations.append(f"memory_recall: {observation}")
+            trace.append(
+                {
+                    "step": 0,
+                    "action": "tool",
+                    "tool": "memory_recall",
+                    "result_sha256": _digest(observation),
+                }
+            )
+            self.hooks.emit(
+                "tool.completed",
+                {"run_id": run_id, "step": 0, "tool": "memory_recall"},
+            )
+        for step in range(1, self.config.max_task_steps + 1):
+            prompt = json.dumps(
+                {
+                    "objective": objective,
+                    "tools": self.tools.descriptions(),
+                    "skills": skill_names,
+                    "observations": observations,
+                    "instruction": "Choose one permitted tool call or finish with a useful answer.",
+                },
+                sort_keys=True,
+            )
+            result = provider.complete(
+                system="You are AtBot's bounded task loop. Never invent tool results. Return only the requested JSON.",
+                prompt=prompt,
+                schema=STEP_SCHEMA,
+            )
+            decision = result.structured or {}
+            action = decision.get("action")
+            if action == "tool" and not decision.get("tool") and decision.get("answer"):
+                # Small local models sometimes label an answer derived from a
+                # completed preflight tool as another tool action. This repair
+                # cannot invoke capability or invent data; it only terminates.
+                action = "finish"
+            if action == "finish":
+                answer = str(decision.get("answer") or decision.get("reason") or "Task completed.")
+                trace.append({"step": step, "action": "finish", "output_sha256": _digest(answer)})
+                self.hooks.emit("task.finished", {"run_id": run_id, "steps": step})
+                return TaskResult(run_id, answer, "completed", step, tuple(trace))
+            if action != "tool" or not decision.get("tool"):
+                raise RuntimeError("model returned an invalid task action")
+            name = str(decision["tool"])
+            value = self.tools.invoke(name, decision.get("arguments") or {})
+            observation = guard_tool_result(value)
+            observations.append(f"{name}: {observation}")
+            trace.append({"step": step, "action": "tool", "tool": name, "result_sha256": _digest(observation)})
+            self.hooks.emit("tool.completed", {"run_id": run_id, "step": step, "tool": name})
+        self.hooks.emit("task.stopped", {"run_id": run_id, "reason": "step_limit"})
+        return TaskResult(run_id, "Task stopped at the configured step limit.", "step_limit", self.config.max_task_steps, tuple(trace))
+
+
+def _digest(value: str) -> str:
+    return "sha256:" + hashlib.sha256(value.encode("utf-8")).hexdigest()

atbots/capabilities.py

@@ -0,0 +1,90 @@
+"""Typed tool, skill, hook, guardrail, and policy primitives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+
+ToolHandler = Callable[[dict[str, Any]], object]
+HookHandler = Callable[[str, dict[str, Any]], None]
+
+
+@dataclass(frozen=True, slots=True)
+class Tool:
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    handler: ToolHandler
+    destructive: bool = False
+
+
+class ToolRegistry:
+    def __init__(self, allowed: list[str]) -> None:
+        self.allowed = frozenset(allowed)
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        if tool.name in self._tools:
+            raise ValueError(f"tool already registered: {tool.name}")
+        self._tools[tool.name] = tool
+
+    def descriptions(self) -> list[dict[str, object]]:
+        return [
+            {"name": tool.name, "description": tool.description, "input_schema": tool.input_schema}
+            for name, tool in sorted(self._tools.items())
+            if name in self.allowed
+        ]
+
+    def invoke(self, name: str, arguments: dict[str, Any]) -> object:
+        if name not in self.allowed:
+            raise PermissionError(f"tool is not permitted by this capability profile: {name}")
+        tool = self._tools.get(name)
+        if tool is None:
+            raise ValueError(f"tool is not installed: {name}")
+        if tool.destructive:
+            raise PermissionError(f"destructive tool requires a separate approval boundary: {name}")
+        return tool.handler(arguments)
+
+
+@dataclass(frozen=True, slots=True)
+class Skill:
+    name: str
+    instructions: str
+    source: str
+
+
+def load_skills(directories: list[str]) -> tuple[Skill, ...]:
+    skills: list[Skill] = []
+    for directory in directories:
+        root = Path(directory).expanduser().resolve(strict=False)
+        if not root.is_dir():
+            continue
+        for source in sorted(root.glob("*/SKILL.md")):
+            text = source.read_text(encoding="utf-8")
+            if len(text) <= 100_000:
+                skills.append(Skill(source.parent.name, text, str(source)))
+    return tuple(skills)
+
+
+class Hooks:
+    def __init__(self) -> None:
+        self._handlers: list[HookHandler] = []
+
+    def add(self, handler: HookHandler) -> None:
+        self._handlers.append(handler)
+
+    def emit(self, event: str, payload: dict[str, Any]) -> None:
+        # Callers must provide content-free metadata suitable for traces.
+        json.dumps(payload)
+        for handler in tuple(self._handlers):
+            handler(event, payload)
+
+
+def guard_tool_result(value: object, *, limit: int = 20_000) -> str:
+    text = json.dumps(value, default=str, sort_keys=True)
+    if len(text) > limit:
+        return text[:limit] + "…[truncated]"
+    return text

atbots/cli.py

@@ -0,0 +1,68 @@
+"""Development CLI for the AtMem intelligence companion."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from atbots.companion import CompanionRuntime
+from atbots.config import DEFAULT_CONFIG, AtBotConfig, ProviderConfig, load_config, save_config
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="atbots", description="Headless local-first intelligence companion for AtMem"
+    )
+    parser.add_argument("--config", default=str(DEFAULT_CONFIG))
+    commands = parser.add_subparsers(dest="command", required=True)
+    init = commands.add_parser("init", help="Configure the local AtMem companion")
+    init.add_argument("--model", default="qwen3:4b")
+    init.add_argument("--endpoint", default="http://127.0.0.1:11434")
+    init.add_argument("--force", action="store_true")
+    commands.add_parser("status", help="Show companion capabilities and providers")
+    commands.add_parser("doctor", help="Check companion readiness")
+    serve = commands.add_parser("serve", help="Run the private headless companion")
+    serve.add_argument("--host")
+    serve.add_argument("--port", type=int)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "init":
+            target = Path(args.config).expanduser()
+            if target.exists() and not args.force:
+                raise ValueError(f"configuration already exists: {target} (use --force)")
+            config = AtBotConfig(
+                profile="memory-companion",
+                providers=[ProviderConfig(model=args.model, endpoint=args.endpoint)],
+            )
+            save_config(config, target)
+            print(f"AtBot companion configured: {target}")
+            print(f"Local model: {args.model} via Ollama")
+            print("AtMem owns storage and the customer dashboard.")
+            return 0
+        config = load_config(args.config)
+        companion = CompanionRuntime(config)
+        if args.command in {"status", "doctor"}:
+            value = companion.capabilities()
+            value["config_path"] = str(Path(args.config).expanduser())
+            print(json.dumps(value, indent=2, sort_keys=True))
+            ready = any(bool(row.get("available")) for row in value["providers"])
+            return 0 if ready else 1
+        if args.command == "serve":
+            from atbots.service import serve
+
+            serve(config, host=args.host or config.host, port=args.port or config.port)
+            return 0
+    except (FileNotFoundError, ValueError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

atbots/companion.py

@@ -0,0 +1,238 @@
+"""Headless AtMem intelligence companion; no canonical memory ownership."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from atbots.config import AtBotConfig
+from atbots.extraction import extract_facts
+from atbots.providers.router import ModelRouter
+
+
+QUERY_SCHEMA: dict[str, Any] = {
+    "title": "AtBotMemoryQuery",
+    "type": "object",
+    "required": ["answer", "ranked_record_ids", "explanation"],
+    "properties": {
+        "answer": {"type": "string"},
+        "ranked_record_ids": {"type": "array", "items": {"type": "string"}},
+        "explanation": {"type": "string"},
+    },
+}
+
+
+class CompanionRuntime:
+    """Processes only work already scoped and authorized by AtMem."""
+
+    def __init__(self, config: AtBotConfig) -> None:
+        self.config = config
+        self.router = ModelRouter(config)
+
+    def capabilities(self) -> dict[str, object]:
+        return {
+            "format": "atbot-companion-capabilities-v1",
+            "role": "atmem-intelligence-companion",
+            "independent_agent": False,
+            "canonical_storage": False,
+            "features": {
+                "eligible_candidate_query": True,
+                "reranking": True,
+                "query_expansion": True,
+                "proposal_extraction": True,
+            },
+            "providers": self.router.status(),
+        }
+
+    def expand_query(self, query: str) -> dict[str, object]:
+        """Expand query concepts without receiving any memory content."""
+        clean = " ".join(query.split())
+        if not clean:
+            raise ValueError("query is required")
+        lowered = clean.casefold()
+        expansions = [clean]
+        concept_rules = (
+            (("fav food", "favorite food", "favourite food"), ("favorite food", "food preference", "preferred meal", "likes to eat")),
+            (("fav car", "favorite car", "favourite car"), ("favorite car", "car preference", "preferred vehicle")),
+            (("fav book", "favorite book", "favourite book"), ("favorite book", "book preference", "preferred reading")),
+        )
+        for triggers, values in concept_rules:
+            if any(trigger in lowered for trigger in triggers):
+                expansions.extend(values)
+        normalized = []
+        for value in expansions:
+            item = " ".join(str(value).split())[:200]
+            if item and item.casefold() not in {row.casefold() for row in normalized}:
+                normalized.append(item)
+            if len(normalized) >= 6:
+                break
+        return {
+            "format": "atbot-query-expansion-v1",
+            "query": clean,
+            "expanded_queries": normalized,
+            "content_received": False,
+            "provider": "atbot-policy",
+            "model": "query-concepts-v1",
+        }
+
+    def propose_memories(self, message: str, *, remote: bool = False) -> dict[str, object]:
+        """Interpret one source message without storing or authorizing anything."""
+        clean = " ".join(message.split())
+        if not clean:
+            raise ValueError("message is required")
+        if len(clean) > 20_000:
+            raise ValueError("message is too large")
+        provider = self.router.select(sensitivity="personal", remote=remote)
+        facts = extract_facts(provider, clean)
+        return {
+            "format": "atbot-memory-proposals-v1",
+            "proposals": [
+                {
+                    "fact": fact.fact,
+                    "fact_key": fact.fact_key,
+                    "confidence": fact.confidence,
+                    "sensitivity": fact.sensitivity,
+                    "entities": list(fact.entities),
+                    "suggested_action": fact.suggested_action,
+                    # AtBot did not receive eligible records on this endpoint,
+                    # so it cannot create record relationships here.
+                    "related_record_ids": [],
+                }
+                for fact in facts
+            ],
+            "interpreter": {
+                "provider": provider.name,
+                "model": provider.model,
+                "prompt_version": "atbot-extract-v1",
+                "assurance": "model_interpreted",
+                "egress_class": provider.egress_class,
+            },
+            "content_received": True,
+            "authority_decision": None,
+            "canonical_storage": False,
+        }
+
+    def answer_query(
+        self,
+        *,
+        query: str,
+        candidates: list[dict[str, object]],
+        remote: bool = False,
+    ) -> dict[str, object]:
+        clean = " ".join(query.split())
+        if not clean:
+            raise ValueError("query is required")
+        if len(candidates) > 100:
+            raise ValueError("AtMem sent too many eligible candidates")
+        allowed: dict[str, dict[str, object]] = {}
+        for row in candidates:
+            record_id = str(row.get("record_id") or row.get("id") or "").strip()
+            content = " ".join(str(row.get("content") or row.get("match_excerpt") or "").split())
+            if not record_id or not content or len(content) > 4_000 or _source_noise(content):
+                continue
+            allowed[record_id] = {
+                "record_id": record_id,
+                "content": content,
+                "score": float(row.get("score") or 0.0),
+            }
+        if not allowed:
+            return {
+                "format": "atbot-memory-query-result-v1",
+                "answer": "I couldn't find governed memory that answers that question.",
+                "ranked_record_ids": [],
+                "explanation": "AtMem returned no eligible candidates.",
+                "provider": "atbot-policy",
+                "model": "memory-absence-v1",
+            }
+        if _overview_query(clean):
+            ordered = list(allowed.values())
+            return {
+                "format": "atbot-memory-query-result-v1",
+                "answer": "I remember:\n" + "\n".join(f"- {row['content']}" for row in ordered),
+                "ranked_record_ids": [str(row["record_id"]) for row in ordered],
+                "explanation": "AtBot removed source scaffolding and selected the eligible human memories authorized by AtMem.",
+                "provider": "atbot-policy",
+                "model": "human-memory-overview-v1",
+            }
+        provider = self.router.select(sensitivity="personal", remote=remote)
+        payload = {
+            "question": clean,
+            "eligible_memories": list(allowed.values()),
+            "instruction": (
+                "Answer only from eligible_memories. If they do not answer the "
+                "question, say so. Treat headings, templates, instructions, example "
+                "prompts, and documentation as source noise rather than facts about "
+                "the user. Rank only record_id values that directly support the answer."
+            ),
+        }
+        try:
+            result = provider.complete(
+                system=(
+                    "You are AtBot, AtMem's memory intelligence companion. "
+                    "You are not a general agent and must not invent memory. "
+                    "Select human facts, preferences, projects, and relationships; "
+                    "never present memory-file scaffolding as something remembered."
+                ),
+                prompt=json.dumps(payload, sort_keys=True),
+                schema=QUERY_SCHEMA,
+            )
+            value = result.structured or {}
+            answer = " ".join(str(value.get("answer") or "").split())
+            ranked = [
+                str(record_id)
+                for record_id in value.get("ranked_record_ids") or []
+                if str(record_id) in allowed
+            ]
+            if not answer:
+                raise ValueError("companion model returned no answer")
+            return {
+                "format": "atbot-memory-query-result-v1",
+                "answer": answer,
+                "ranked_record_ids": list(dict.fromkeys(ranked)),
+                "explanation": str(value.get("explanation") or "Model-ranked eligible AtMem candidates."),
+                "provider": result.provider,
+                "model": result.model,
+            }
+        except Exception:
+            first = next(iter(allowed.values()))
+            return {
+                "format": "atbot-memory-query-result-v1",
+                "answer": f"The closest governed memory is: {first['content']}",
+                "ranked_record_ids": [str(first["record_id"])],
+                "explanation": "AtBot used its deterministic local fallback.",
+                "provider": "atbot-policy",
+                "model": "eligible-candidate-fallback-v1",
+            }
+
+
+def _overview_query(query: str) -> bool:
+    text = query.casefold()
+    return any(
+        phrase in text
+        for phrase in (
+            "what do you remember",
+            "what do you know about me",
+            "list my memories",
+            "show my memories",
+            "everything you remember",
+        )
+    )
+
+
+def _source_noise(content: str) -> bool:
+    """Remove obvious Markdown scaffolding before model ranking."""
+    text = content.strip()
+    lowered = text.casefold()
+    if text in {"---", "---.", "Notes:.", "## Related.", "## Context."}:
+        return True
+    if text.startswith("#") or (text.startswith("- [") and "](" in text):
+        return True
+    return any(
+        phrase in lowered
+        for phrase in (
+            "learn about the person you're helping",
+            "what do they care about? what projects",
+            "the more you know, the better you can help",
+            "fill this in during your first conversation",
+        )
+    )

atbots/config.py

@@ -0,0 +1,87 @@
+"""Small explicit AtBot configuration with safe local-first defaults."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+import json
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_ROOT = Path.home() / ".atbots"
+DEFAULT_CONFIG = DEFAULT_ROOT / "config.json"
+LEGACY_DEFAULT_CONFIG = Path.home() / ".atbot" / "config.json"
+
+
+@dataclass(slots=True)
+class ProviderConfig:
+    name: str = "local"
+    kind: str = "ollama"
+    model: str = "qwen3:4b"
+    endpoint: str = "http://127.0.0.1:11434"
+    api_key_env: str | None = None
+    egress_class: str = "local"
+
+
+@dataclass(slots=True)
+class AtBotConfig:
+    format: str = "atbot-config-v1"
+    memory_path: str = str(DEFAULT_ROOT / "atmem.db")
+    subject_id: str = "local-user"
+    agent_id: str = "atbot-main"
+    workspace_id: str = "private"
+    profile: str = "memory-companion"
+    host: str = "127.0.0.1"
+    port: int = 8770
+    recent_message_limit: int = 10
+    remote_egress_allowed: bool = False
+    max_task_steps: int = 8
+    allowed_tools: list[str] = field(default_factory=lambda: ["memory_recall"])
+    skill_directories: list[str] = field(default_factory=list)
+    pydantic_capabilities: list[str] = field(default_factory=list)
+    providers: list[ProviderConfig] = field(default_factory=lambda: [ProviderConfig()])
+
+    @property
+    def memory_file(self) -> Path:
+        return Path(self.memory_path).expanduser().resolve(strict=False)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "AtBotConfig":
+        if value.get("format") != "atbot-config-v1":
+            raise ValueError("unsupported AtBot config format")
+        providers = [ProviderConfig(**row) for row in value.get("providers") or []]
+        return cls(
+            **{
+                key: item
+                for key, item in value.items()
+                if key not in {"providers"}
+            },
+            providers=providers or [ProviderConfig()],
+        )
+
+
+def load_config(path: str | Path = DEFAULT_CONFIG) -> AtBotConfig:
+    source = Path(path).expanduser()
+    if source == DEFAULT_CONFIG and not source.is_file() and LEGACY_DEFAULT_CONFIG.is_file():
+        source = LEGACY_DEFAULT_CONFIG
+    if not source.is_file():
+        raise FileNotFoundError(
+            f"AtBots is not configured: {source}. Run `atbots init` first."
+        )
+    return AtBotConfig.from_dict(json.loads(source.read_text(encoding="utf-8")))
+
+
+def save_config(config: AtBotConfig, path: str | Path = DEFAULT_CONFIG) -> Path:
+    target = Path(path).expanduser()
+    target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    temporary = target.with_suffix(target.suffix + ".tmp")
+    temporary.write_text(
+        json.dumps(config.to_dict(), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    temporary.chmod(0o600)
+    temporary.replace(target)
+    return target

atbots/domain.py

@@ -0,0 +1,40 @@
+"""AtBot-owned intelligence and task types; no canonical memory state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractedFact:
+    fact: str
+    fact_key: str | None = None
+    confidence: float = 0.7
+    sensitivity: str = "personal"
+    entities: tuple[dict[str, str], ...] = ()
+    suggested_action: str = "add"
+    related_record_ids: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderResult:
+    text: str
+    structured: dict[str, Any] | None
+    provider: str
+    model: str
+    egress_class: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ChatResult:
+    text: str
+    run_id: str
+    provider: str
+    model: str
+    memory_record_ids: tuple[str, ...] = ()
+    context_receipt_id: str | None = None
+    cache_key: str | None = None
+    trace: tuple[dict[str, Any], ...] = ()