fcht-agent 0.1.0__py3-none-any.whl

fcht_agent/__init__.py

@@ -0,0 +1,13 @@
+"""
+FCHT Agent - First-Class Hermes Tool Agent
+Offline ReAct agent with persistent memory (episodic + semantic)
+"""
+
+__version__ = "0.1.0"
+__author__ = "Joseph Brown & Newton"
+__license__ = "MIT"
+
+from fcht_agent.core.agent import FCHTAgent
+from fcht_agent.config.schema import AgentConfig
+
+__all__ = ["FCHTAgent", "AgentConfig", "__version__"]

fcht_agent/cli/main.py

@@ -0,0 +1,317 @@
+"""
+FCHT Agent CLI - Command line interface.
+"""
+
+import argparse
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+from dataclasses import asdict
+
+from fcht_agent.config.schema import AgentConfig
+from fcht_agent.core.agent import create_agent
+from fcht_agent.skills.registry import create_skill_registry, SkillMetadata
+
+
+def setup_logging(level: str, json_format: bool = False) -> None:
+    """Configure logging."""
+    fmt = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
+    if json_format:
+        try:
+            import pythonjsonlogger.jsonlogger
+            fmt = "%(asctime)s %(levelname)s %(name)s %(message)s"
+            handler = logging.StreamHandler()
+            handler.setFormatter(pythonjsonlogger.jsonlogger.JsonFormatter(fmt))
+            logging.getLogger().handlers = [handler]
+        except ImportError:
+            pass
+    else:
+        logging.basicConfig(level=level, format=fmt, datefmt="%H:%M:%S")
+
+
+def _normalize_path(path_str: str) -> Path:
+    """Normalize a path string to absolute Path, handling Windows quirks and duplicated components."""
+    expanded = os.path.expanduser(os.path.expandvars(path_str))
+    normalized = os.path.normpath(expanded)
+    absolute = os.path.abspath(normalized)
+    path = Path(absolute)
+    
+    parts = path.parts
+    if len(parts) >= 2 and parts[-1] == parts[-2]:
+        path = Path(*parts[:-1])
+    
+    return path
+
+
+def load_config(config_path: Optional[Path], working_dir: Optional[str] = None) -> AgentConfig:
+    """Load configuration from file or defaults. Does NOT resolve paths yet."""
+    if config_path and config_path.exists():
+        return AgentConfig.from_yaml(config_path)
+    return AgentConfig()
+
+
+def _normalize_path(path_str: str) -> Path:
+    """Normalize a path string to absolute Path, handling Windows quirks and duplicated components."""
+    expanded = os.path.expanduser(os.path.expandvars(path_str))
+    normalized = os.path.normpath(expanded)
+    absolute = os.path.abspath(normalized)
+    path = Path(absolute)
+    
+    parts = path.parts
+    if len(parts) >= 2 and parts[-1] == parts[-2]:
+        path = Path(*parts[:-1])
+    
+    return path
+
+
+def load_config(config_path: Optional[Path], working_dir: Optional[str] = None) -> AgentConfig:
+    """Load configuration from file or defaults. Does NOT resolve paths yet."""
+    if config_path and config_path.exists():
+        return AgentConfig.from_yaml(config_path)
+    return AgentConfig()
+
+
+def _prepare_config(config: AgentConfig, working_dir: Optional[str] = None) -> AgentConfig:
+    """Apply working directory and resolve all paths."""
+    if working_dir:
+        config.working_dir = _normalize_path(working_dir)
+    else:
+        config.working_dir = _normalize_path(str(Path.cwd()))
+    config.resolve_paths()
+    return config
+
+
+def _prepare_config_with_skills(config: AgentConfig, working_dir: Optional[str] = None) -> AgentConfig:
+    """Prepare config and ensure skills directory exists."""
+    config = _prepare_config(config, working_dir)
+    skills_dir = config.working_dir / "memory" / "skills"
+    skills_dir.mkdir(parents=True, exist_ok=True)
+    return config
+
+
+def _safe_print(text: str) -> None:
+    """Print with ASCII fallback for Windows console."""
+    try:
+        print(text)
+    except UnicodeEncodeError:
+        print(text.replace("\u2713", "[OK]").replace("\u2717", "[ERR]"))
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    """Run a single task."""
+    config = load_config(Path(args.config) if args.config else None)
+    config = _prepare_config_with_skills(config, args.working_dir)
+    
+    setup_logging(args.log_level, args.json_logs)
+    
+    if args.quiet:
+        logging.getLogger().setLevel(logging.WARNING)
+    
+    agent = create_agent(config)
+    result = agent.run(args.task)
+    
+    if args.json:
+        print(json.dumps({
+            "result": result.result,
+            "episodes_added": result.episodes_added,
+            "steps_taken": result.steps_taken,
+            "success": result.success
+        }))
+    else:
+        _safe_print(result.result)
+    
+    return 0 if result.success else 1
+
+
+def cmd_config(args: argparse.Namespace) -> int:
+    """Config management."""
+    config = load_config(Path(args.config) if args.config else None)
+    config = _prepare_config(config, args.working_dir)
+    
+    if args.show:
+        _safe_print(config.model_dump_json(indent=2))
+    elif args.init:
+        out = Path(args.init)
+        config.to_yaml(out)
+        _safe_print(f"Config written to {out}")
+    elif args.validate:
+        _safe_print("Config valid [OK]")
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    """Health check."""
+    config = load_config(Path(args.config) if args.config else None)
+    config = _prepare_config(config, args.working_dir)
+    
+    _safe_print("FCHT Agent Health Check")
+    _safe_print("=" * 40)
+    
+    import requests
+    try:
+        resp = requests.get(f"{config.ollama.host}/api/tags", timeout=5)
+        if resp.ok:
+            models = resp.json().get("models", [])
+            _safe_print(f"[OK] Ollama: {config.ollama.host}")
+            _safe_print(f"  Models: {[m['name'] for m in models]}")
+            if config.ollama.model in [m['name'] for m in models]:
+                _safe_print(f"  [OK] Target model '{config.ollama.model}' available")
+            else:
+                _safe_print(f"  [ERR] Target model '{config.ollama.model}' NOT found")
+        else:
+            _safe_print(f"[ERR] Ollama: HTTP {resp.status_code}")
+            return 1
+    except Exception as e:
+        _safe_print(f"[ERR] Ollama: {e}")
+        return 1
+    
+    for name, path in [("Episodic", config.memory.episodes_path), ("Semantic", config.memory.chroma_path)]:
+        if path.parent.exists():
+            _safe_print(f"[OK] {name} memory dir: {path.parent}")
+        else:
+            _safe_print(f"[ERR] {name} memory dir missing: {path.parent}")
+    
+    if config.working_dir.exists():
+        _safe_print(f"[OK] Working dir: {config.working_dir}")
+    else:
+        _safe_print(f"[ERR] Working dir missing: {config.working_dir}")
+        return 1
+    
+    _safe_print("\nAll checks passed [OK]")
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    """Show version."""
+    from fcht_agent import __version__
+    _safe_print(f"fcht-agent {__version__}")
+    return 0
+
+
+def cmd_skill(args: argparse.Namespace) -> int:
+    """Skill management."""
+    config = load_config(Path(args.config) if args.config else None)
+    config = _prepare_config_with_skills(config, args.working_dir)
+    
+    registry = create_skill_registry(config.working_dir / "memory" / "skills")
+    
+    if args.skill_list:
+        skills = registry.list_skills()
+        if args.json:
+            print(json.dumps([asdict(s) for s in skills]))
+        else:
+            if not skills:
+                _safe_print("No skills installed")
+            else:
+                _safe_print("Installed skills:")
+                for s in skills:
+                    _safe_print(f"  {s.name} v{s.version} - {s.description}")
+    elif args.create:
+        meta = registry.create_skill(args.create, args.description or "", args.entry_point or "")
+        _safe_print(f"Created skill: {meta.name} v{meta.version}")
+    elif args.info:
+        if not registry.is_installed(args.info):
+            _safe_print(f"[ERR] Skill not found: {args.info}")
+            return 1
+        meta = registry.get_metadata(args.info)
+        if args.json:
+            print(json.dumps(asdict(meta)))
+        else:
+            _safe_print(f"Name: {meta.name}")
+            _safe_print(f"Version: {meta.version}")
+            _safe_print(f"Description: {meta.description}")
+            _safe_print(f"Author: {meta.author}")
+            _safe_print(f"Created: {meta.created}")
+            _safe_print(f"Updated: {meta.updated}")
+            _safe_print(f"Dependencies: {', '.join(meta.dependencies) or 'none'}")
+            _safe_print(f"Tags: {', '.join(meta.tags) or 'none'}")
+            _safe_print(f"Entry point: {meta.entry_point or 'none'}")
+    elif args.uninstall:
+        if registry.uninstall_skill(args.uninstall):
+            _safe_print(f"Uninstalled skill: {args.uninstall}")
+        else:
+            _safe_print(f"[ERR] Skill not found: {args.uninstall}")
+            return 1
+    elif args.search:
+        results = registry.search_skills(args.search)
+        if args.json:
+            print(json.dumps([asdict(s) for s in results]))
+        else:
+            if not results:
+                _safe_print("No skills found")
+            else:
+                _safe_print(f"Found {len(results)} skill(s):")
+                for s in results:
+                    _safe_print(f"  {s.name} v{s.version} - {s.description}")
+    elif args.install:
+        meta = registry.install_skill(Path(args.install), overwrite=args.force)
+        _safe_print(f"Installed skill: {meta.name} v{meta.version}")
+    else:
+        _safe_print("Use --help for skill commands")
+    return 0
+
+
+def _safe_print(text: str) -> None:
+    try:
+        print(text)
+    except UnicodeEncodeError:
+        print(text.replace("\u2713", "[OK]").replace("\u2717", "[ERR]"))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="fcht-agent",
+        description="First-Class Hermes Tool Agent - Offline ReAct agent with persistent memory"
+    )
+    parser.add_argument("--config", "-c", help="Path to config YAML")
+    parser.add_argument("--working-dir", "-w", help="Working directory")
+    parser.add_argument("--log-level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR"])
+    parser.add_argument("--json-logs", action="store_true", help="JSON structured logs")
+    parser.add_argument("--quiet", "-q", action="store_true", help="Suppress non-error output")
+    parser.add_argument("--json", "-j", action="store_true", help="JSON output")
+    
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    
+    # run
+    run_p = subparsers.add_parser("run", help="Run a task")
+    run_p.add_argument("task", help="Task description")
+    run_p.set_defaults(func=cmd_run)
+    
+    # config
+    config_p = subparsers.add_parser("config", help="Config management")
+    config_p.add_argument("--show", action="store_true", help="Show current config")
+    config_p.add_argument("--init", metavar="PATH", help="Write default config to file")
+    config_p.add_argument("--validate", action="store_true", help="Validate config")
+    config_p.set_defaults(func=cmd_config)
+    
+    # doctor
+    doctor_p = subparsers.add_parser("doctor", help="Health check")
+    doctor_p.set_defaults(func=cmd_doctor)
+    
+    # skill
+    skill_p = subparsers.add_parser("skill", help="Skill management")
+    skill_p.add_argument("--list", dest="skill_list", action="store_true", help="List installed skills")
+    skill_p.add_argument("--create", metavar="NAME", help="Create new skill scaffold")
+    skill_p.add_argument("--info", metavar="NAME", help="Show skill metadata")
+    skill_p.add_argument("--install", metavar="PATH", help="Install skill from directory/zip")
+    skill_p.add_argument("--uninstall", metavar="NAME", help="Uninstall skill")
+    skill_p.add_argument("--search", metavar="QUERY", help="Search skills")
+    skill_p.add_argument("--description", metavar="TEXT", help="Skill description (for create)")
+    skill_p.add_argument("--entry-point", metavar="PATH", help="Entry point (for create)")
+    skill_p.add_argument("--force", action="store_true", help="Overwrite existing")
+    skill_p.add_argument("--json", action="store_true", help="JSON output")
+    skill_p.set_defaults(func=cmd_skill)
+    
+    # version
+    version_p = subparsers.add_parser("version", help="Show version")
+    version_p.set_defaults(func=cmd_version)
+    
+    args = parser.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fcht_agent/config/__init__.py

@@ -0,0 +1,3 @@
+from fcht_agent.config.schema import AgentConfig, DEFAULT_CONFIG
+
+__all__ = ["AgentConfig", "DEFAULT_CONFIG"]

fcht_agent/config/schema.py

@@ -0,0 +1,102 @@
+"""
+Configuration schema for FCHT Agent using Pydantic.
+Supports YAML files, environment variables, and validation.
+"""
+
+from pathlib import Path
+from typing import Optional, Literal
+from pydantic import BaseModel, Field, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class OllamaConfig(BaseModel):
+    host: str = Field(default="http://localhost:11434", description="Ollama API endpoint")
+    model: str = Field(default="qwen2.5:7b", description="Model name to use")
+    temperature: float = Field(default=0.1, ge=0.0, le=2.0, description="Sampling temperature")
+    timeout: int = Field(default=120, description="Request timeout in seconds")
+    num_gpu: int = Field(default=-1, description="GPU layers (-1=auto, 0=CPU only)")
+
+
+class MemoryConfig(BaseModel):
+    episodes_path: Path = Field(default=Path("memory/episodes.jsonl"), description="Episodic memory file")
+    max_few_shot: int = Field(default=3, ge=0, le=20, description="Max episodes for few-shot")
+    chroma_path: Path = Field(default=Path("memory/chroma"), description="ChromaDB directory")
+    embed_model: str = Field(default="all-MiniLM-L6-v2", description="Sentence transformer model")
+    embed_cache_dir: Optional[Path] = Field(default=None, description="Embedding model cache directory")
+
+
+class AgentSettings(BaseModel):
+    max_steps: int = Field(default=10, ge=1, le=50, description="Max ReAct steps")
+    system_prompt: str = Field(
+        default="You are a precise, helpful assistant. Use tools to accomplish tasks. "
+                "Output ONLY JSON tool calls. When done, respond with 'DONE: <result>'.",
+        description="System prompt for the agent"
+    )
+
+
+class DaemonConfig(BaseModel):
+    enabled: bool = Field(default=True, description="Run daemon mode")
+    host: str = Field(default="127.0.0.1", description="Daemon bind address")
+    port: int = Field(default=8765, description="Daemon port")
+    max_workers: int = Field(default=4, description="Concurrent workers")
+
+
+class LoggingConfig(BaseModel):
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = Field(default="INFO")
+    json_format: bool = Field(default=False, description="JSON structured logs")
+    file: Optional[Path] = Field(default=None, description="Log file path")
+
+
+class AgentConfig(BaseSettings):
+    """Main configuration - loads from YAML, env vars, and defaults."""
+    
+    model_config = SettingsConfigDict(
+        env_prefix="FCHT_",
+        env_nested_delimiter="__",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+    
+    ollama: OllamaConfig = Field(default_factory=OllamaConfig)
+    memory: MemoryConfig = Field(default_factory=MemoryConfig)
+    agent: AgentSettings = Field(default_factory=AgentSettings)
+    daemon: DaemonConfig = Field(default_factory=DaemonConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    
+    working_dir: Path = Field(default=Path.cwd(), description="Working directory")
+    
+    @field_validator("working_dir", mode="before")
+    @classmethod
+    def resolve_working_dir(cls, v):
+        return Path(v).expanduser().resolve()
+    
+    def resolve_paths(self) -> "AgentConfig":
+        """Resolve all relative paths against working_dir."""
+        # Only resolve if path is relative
+        if not self.memory.episodes_path.is_absolute():
+            self.memory.episodes_path = (self.working_dir / self.memory.episodes_path).resolve()
+        if not self.memory.chroma_path.is_absolute():
+            self.memory.chroma_path = (self.working_dir / self.memory.chroma_path).resolve()
+        if self.memory.embed_cache_dir and not self.memory.embed_cache_dir.is_absolute():
+            self.memory.embed_cache_dir = (self.working_dir / self.memory.embed_cache_dir).resolve()
+        return self
+    
+    @classmethod
+    def from_yaml(cls, path: Path) -> "AgentConfig":
+        """Load from YAML file."""
+        import yaml
+        with open(path) as f:
+            data = yaml.safe_load(f) or {}
+        return cls(**data).resolve_paths()
+    
+    def to_yaml(self, path: Path) -> None:
+        """Save to YAML file."""
+        import yaml
+        data = self.model_dump(mode="json")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            yaml.dump(data, f, sort_keys=False)
+
+
+DEFAULT_CONFIG = AgentConfig()

fcht_agent/core/__init__.py

@@ -0,0 +1,3 @@
+from fcht_agent.core.agent import FCHTAgent, create_agent, AgentResult
+
+__all__ = ["FCHTAgent", "create_agent", "AgentResult"]

fcht_agent/core/agent.py

@@ -0,0 +1,214 @@
+"""
+FCHT Agent - Core ReAct loop with memory and tools.
+"""
+
+import json
+import re
+import logging
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass
+
+import requests
+
+from fcht_agent.config.schema import AgentConfig
+from fcht_agent.memory.episodic import EpisodicMemory
+from fcht_agent.memory.semantic import SemanticMemory
+from fcht_agent.tools.registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentResult:
+    result: str
+    episodes_added: int
+    steps_taken: int
+    success: bool
+
+
+class FCHTAgent:
+    """Main agent class."""
+    
+    def __init__(self, config: AgentConfig):
+        self.config = config
+        self.episodic = EpisodicMemory(config.memory.episodes_path, config.memory.max_few_shot)
+        self.semantic = SemanticMemory(config.memory.chroma_path, config.memory.embed_model, config.memory.embed_cache_dir)
+        self.tools = ToolRegistry(config.working_dir)
+        
+        # Register memory tools
+        self._register_memory_tools()
+        
+        # Ollama client
+        self.ollama_url = f"{config.ollama.host}/api/generate"
+        self.model = config.ollama.model
+        self.temperature = config.ollama.temperature
+        self.timeout = config.ollama.timeout
+        
+        # System prompt
+        self.system_prompt = config.agent.system_prompt
+    
+    def _register_memory_tools(self) -> None:
+        """Register memory tools with the registry."""
+        from fcht_agent.tools.registry import Tool
+        
+        def remember(text: str, metadata: Dict = None) -> Dict[str, Any]:
+            return self.semantic.remember(text, metadata)
+        
+        def retrieve(query: str, n_results: int = 5) -> Dict[str, Any]:
+            return self.semantic.retrieve(query, n_results)
+        
+        self.tools.register(Tool(
+            name="remember",
+            func=remember,
+            description="Store a fact or document in semantic memory",
+            schema={
+                "type": "object",
+                "properties": {
+                    "text": {"type": "string", "description": "Text to remember"},
+                    "metadata": {"type": "object", "description": "Optional metadata"}
+                },
+                "required": ["text"]
+            }
+        ))
+        
+        self.tools.register(Tool(
+            name="retrieve",
+            func=retrieve,
+            description="Search semantic memory for relevant information",
+            schema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query"},
+                    "n_results": {"type": "integer", "default": 5}
+                },
+                "required": ["query"]
+            }
+        ))
+    
+    def _call_ollama(self, prompt: str) -> str:
+        """Call Ollama API."""
+        payload = {
+            "model": self.model,
+            "prompt": prompt,
+            "stream": False,
+            "options": {"temperature": self.temperature}
+        }
+        try:
+            resp = requests.post(self.ollama_url, json=payload, timeout=self.timeout)
+            resp.raise_for_status()
+            return resp.json().get("response", "").strip()
+        except requests.RequestException as e:
+            logger.error(f"Ollama error: {e}")
+            raise
+    
+    def _build_prompt(self, history: str, user_task: str) -> str:
+        """Build the full prompt for the model."""
+        few_shot = self.episodic.build_few_shot(self.config.memory.max_few_shot)
+        tool_docs = self.tools.format_for_prompt()
+        
+        return f"""{self.system_prompt}
+
+{tool_docs}
+
+{few_shot}
+### Current Task
+User: {user_task}
+
+{history}
+Assistant:"""
+    
+    def _parse_action(self, response: str) -> Optional[Dict]:
+        """Parse tool call from model response."""
+        match = re.search(r"```json\s*(\{.*?\})\s*```", response, re.DOTALL)
+        if not match:
+            match = re.search(r'(\{[\s\S]*"tool"[\s\S]*\})', response)
+        if match:
+            try:
+                return json.loads(match.group(1))
+            except json.JSONDecodeError:
+                pass
+        return None
+    
+    def _format_observation(self, result: Dict) -> str:
+        """Format tool result for next prompt."""
+        if "error" in result:
+            return f"Tool Error: {result['error']}"
+        
+        out = []
+        for k, v in result.items():
+            if isinstance(v, str) and len(v) > 500:
+                v = v[:500] + "... [truncated]"
+            elif isinstance(v, (list, dict)):
+                v = json.dumps(v)[:500] + "... [truncated]" if len(json.dumps(v)) > 500 else json.dumps(v)
+            out.append(f"{k}: {v}")
+        return "Tool Result:\n" + "\n".join(out)
+    
+    def run(self, user_task: str) -> AgentResult:
+        """Run the agent on a task."""
+        history = ""
+        episodes_before = self.episodic.count()
+        steps_taken = 0
+        
+        for step in range(self.config.agent.max_steps):
+            steps_taken = step + 1
+            logger.debug(f"Step {steps_taken}/{self.config.agent.max_steps}")
+            
+            prompt = self._build_prompt(history, user_task)
+            response = self._call_ollama(prompt)
+            
+            if "DONE:" in response:
+                final = response.split("DONE:", 1)[1].strip()
+                self.episodic.add(user_task, final)
+                return AgentResult(
+                    result=final,
+                    episodes_added=self.episodic.count() - episodes_before,
+                    steps_taken=steps_taken,
+                    success=True
+                )
+            
+            action = self._parse_action(response)
+            if action:
+                tool_name = action.get("tool")
+                args = action.get("args", {})
+                try:
+                    result = self.tools.execute(tool_name, args)
+                except Exception as e:
+                    result = {"error": str(e)}
+                
+                obs = self._format_observation(result)
+                history += f"\nAssistant: {response}\n{obs}\n"
+            else:
+                history += f"\nAssistant: {response}\n"
+        
+        return AgentResult(
+            result="Max steps reached without DONE.",
+            episodes_added=self.episodic.count() - episodes_before,
+            steps_taken=steps_taken,
+            success=False
+        )
+    
+    def close(self) -> None:
+        """Close resources (ChromaDB connections, etc.)."""
+        try:
+            self.semantic.close()
+        except Exception:
+            pass
+        try:
+            self.episodic = None
+        except Exception:
+            pass
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+
+def create_agent(config: Optional[AgentConfig] = None) -> FCHTAgent:
+    """Factory function to create agent from config."""
+    if config is None:
+        config = AgentConfig()
+    return FCHTAgent(config)