fcht-agent 0.1.0__tar.gz

fcht_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Brown & Newton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fcht_agent-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: fcht-agent
+Version: 0.1.0
+Summary: First-Class Hermes Tool Agent — Offline ReAct agent with dual memory (episodic + semantic), skill learning, and daemon mode
+Author-email: Joseph Brown <commanderbrown@ppcrepair.com>
+Maintainer-email: FCHT Team <commanderbrown@ppcrepair.com>
+License: MIT
+Project-URL: Homepage, https://github.com/fcht-agent/fcht-agent
+Project-URL: Repository, https://github.com/fcht-agent/fcht-agent
+Project-URL: Issues, https://github.com/fcht-agent/fcht-agent/issues
+Project-URL: Documentation, https://github.com/fcht-agent/fcht-agent/blob/main/README.md
+Project-URL: Changelog, https://github.com/fcht-agent/fcht-agent/blob/main/CHANGELOG.md
+Keywords: ai-agent,offline-ai,local-llm,react-agent,rag,chromadb,ollama,autonomous-agent,hermes,memory-augmented
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: chromadb>=1.5
+Requires-Dist: sentence-transformers>=5.5
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pydantic-settings>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Provides-Extra: gpu
+Requires-Dist: torch>=2.0; extra == "gpu"
+Provides-Extra: all
+Requires-Dist: torch>=2.0; extra == "all"
+Dynamic: license-file
+Dynamic: requires-python
+
+# FCHT Agent — First-Class Hermes Tool Agent
+
+> **Offline ReAct agent with persistent dual-memory (episodic + semantic) — runs entirely on your hardware.**
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](https://github.com)
+
+---
+
+## 🎯 What Is This?
+
+**FCHT Agent** is a local-first AI agent that runs **100% offline** on your machine using [Ollama](https://ollama.ai) and your choice of local LLM (default: `qwen2.5:7b`). It features:
+
+| Capability | Description |
+|------------|-------------|
+| **ReAct Loop** | Think → Act → Observe reasoning with tool use |
+| **Episodic Memory** | JSONL few-shot history for context-aware responses |
+| **Semantic Memory** | ChromaDB + sentence-transformers for RAG |
+| **Skill System** | Agent writes executable Python tools to `memory/skills/` |
+| **7 Built-in Tools** | shell, read/write files, python_exec, list_files, remember, retrieve |
+| **Daemon Mode** | JSON-RPC over stdin/stdout for low-latency reuse |
+| **CLI + Config** | Full argparse interface, YAML/env config, health checks |
+
+**Zero cloud calls after initial model pull. Your data never leaves your machine.**
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.10+
+- [Ollama](https://ollama.ai) installed and running
+- Pull a model: `ollama pull qwen2.5:7b`
+
+### Install
+```bash
+pip install -e .
+# or from PyPI (when published)
+pip install fcht-agent
+```
+
+### Verify Installation
+```bash
+fcht-agent doctor
+# ✓ Ollama: http://localhost:11434
+# ✓ Target model 'qwen2.5:7b' available
+# ✓ All memory dirs exist
+# All checks passed ✓
+```
+
+### Run a Task
+```bash
+# One-shot
+fcht-agent run "What is the project name? Use retrieve."
+
+# JSON output for scripting
+fcht-agent --json run "List skills in memory/skills"
+# {"result": "...", "episodes_added": 1, "steps_taken": 2, "success": true}
+```
+
+### Daemon Mode (Fast, Model Stays Loaded)
+```bash
+# Terminal 1: start daemon
+fcht-agent-daemon
+# {"jsonrpc": "2.0", "method": "ready", "params": {"model": "qwen2.5:7b"}}
+
+# Terminal 2: send requests
+echo '{"task": "What is the project name?", "id": "req-1"}' | fcht-agent-daemon
+# {"id": "req-1", "result": {"output": "...", "episodes_added": 1, "steps_taken": 2, "success": true}}
+```
+
+---
+
+## 🧠 Memory Architecture
+
+```
+memory/
+├── episodes.jsonl          # Episodic: few-shot conversation history
+├── chroma/                 # Semantic: ChromaDB vector store
+│   ├── chroma.sqlite3
+│   └── ...
+└── skills/                 # Procedural: learned Python tools
+    ├── hello.py
+    ├── greeting.py
+    └── fibonacci.py
+```
+
+| Memory Type | Storage | Use Case |
+|-------------|---------|----------|
+| **Episodic** | JSONL (append-only) | Few-shot prompting, conversation continuity |
+| **Semantic** | ChromaDB + embeddings | Fact retrieval, RAG, similarity search |
+| **Procedural** | Python files in `skills/` | Learned procedures, reusable tools |
+
+---
+
+## 🛠 Built-in Tools
+
+| Tool | Description | Example |
+|------|-------------|---------|
+| `shell` | Run shell commands | `{"tool": "shell", "args": {"cmd": "ls -la"}}` |
+| `read_file` | Read file contents | `{"tool": "read_file", "args": {"path": "config.yaml"}}` |
+| `write_file` | Write file contents | `{"tool": "write_file", "args": {"path": "out.py", "content": "print(1)"}}` |
+| `python_exec` | Execute Python code | `{"tool": "python_exec", "args": {"code": "print(2+2)"}}` |
+| `list_files` | List directory | `{"tool": "list_files", "args": {"path": "memory/skills"}}` |
+| `remember` | Store in semantic memory | `{"tool": "remember", "args": {"text": "API key is xyz", "metadata": {"type": "secret"}}}` |
+| `retrieve` | Search semantic memory | `{"tool": "retrieve", "args": {"query": "API key", "n_results": 3}}` |
+
+---
+
+## ⚙️ Configuration
+
+### YAML Config (`config.yaml`)
+```yaml
+ollama:
+  host: "http://localhost:11434"
+  model: "qwen2.5:7b"
+  temperature: 0.1
+  timeout: 120
+
+memory:
+  episodes_path: "memory/episodes.jsonl"
+  max_few_shot: 3
+  chroma_path: "memory/chroma"
+  embed_model: "all-MiniLM-L6-v2"
+  embed_cache_dir: "~/.cache/fcht-agent/embeddings"
+
+agent:
+  max_steps: 10
+  system_prompt: |
+    You are a precise, helpful assistant. Use tools to accomplish tasks.
+    Output ONLY JSON tool calls. When done, respond with 'DONE: <result>'.
+
+daemon:
+  enabled: true
+  host: "127.0.0.1"
+  port: 8765
+```
+
+### Environment Variables (override any setting)
+```bash
+FCHT_OLLAMA__MODEL=llama3.1
+FCHT_MEMORY__MAX_FEW_SHOT=5
+FCHT_AGENT__MAX_STEPS=15
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Memory tests
+pytest tests/test_memory.py -v
+
+# Agent tests
+pytest tests/test_agent.py -v
+```
+
+---
+
+## 📦 Project Structure
+```
+fcht_agent/
+├── __init__.py              # Exports: FCHTAgent, AgentConfig, __version__
+├── config/schema.py         # Pydantic settings (YAML/env/file)
+├── core/agent.py            # ReAct loop + Ollama client + tools
+├── memory/
+│   ├── episodic.py          # JSONL few-shot memory
+│   ├── semantic.py          # ChromaDB + cached embeddings
+│   └── embeddings.py        # Singleton embedding model
+├── tools/registry.py        # 7 built-in tools
+├── cli/main.py              # argparse CLI: run, config, doctor, version
+├── daemon/server.py         # JSON-RPC stdin/stdout daemon
+tests/
+├── test_memory.py           # Memory module tests
+├── test_agent.py            # Agent integration tests
+setup.py                     # Setuptools config
+```
+
+---
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repo
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure `pytest tests/` passes
+5. Submit PR
+
+---
+
+## 🙋 Support
+
+- **Issues**: GitHub Issues
+- **Discussions**: GitHub Discussions
+- **Security**: security@example.com (PGP key available)
+
+---
+
+*Built with ❤️ for local-first AI. Runs on a GTX 1080 Ti (11GB) with qwen2.5:7b.*

fcht_agent-0.1.0/README.md

@@ -0,0 +1,209 @@
+# FCHT Agent — First-Class Hermes Tool Agent
+
+> **Offline ReAct agent with persistent dual-memory (episodic + semantic) — runs entirely on your hardware.**
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](https://github.com)
+
+---
+
+## 🎯 What Is This?
+
+**FCHT Agent** is a local-first AI agent that runs **100% offline** on your machine using [Ollama](https://ollama.ai) and your choice of local LLM (default: `qwen2.5:7b`). It features:
+
+| Capability | Description |
+|------------|-------------|
+| **ReAct Loop** | Think → Act → Observe reasoning with tool use |
+| **Episodic Memory** | JSONL few-shot history for context-aware responses |
+| **Semantic Memory** | ChromaDB + sentence-transformers for RAG |
+| **Skill System** | Agent writes executable Python tools to `memory/skills/` |
+| **7 Built-in Tools** | shell, read/write files, python_exec, list_files, remember, retrieve |
+| **Daemon Mode** | JSON-RPC over stdin/stdout for low-latency reuse |
+| **CLI + Config** | Full argparse interface, YAML/env config, health checks |
+
+**Zero cloud calls after initial model pull. Your data never leaves your machine.**
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.10+
+- [Ollama](https://ollama.ai) installed and running
+- Pull a model: `ollama pull qwen2.5:7b`
+
+### Install
+```bash
+pip install -e .
+# or from PyPI (when published)
+pip install fcht-agent
+```
+
+### Verify Installation
+```bash
+fcht-agent doctor
+# ✓ Ollama: http://localhost:11434
+# ✓ Target model 'qwen2.5:7b' available
+# ✓ All memory dirs exist
+# All checks passed ✓
+```
+
+### Run a Task
+```bash
+# One-shot
+fcht-agent run "What is the project name? Use retrieve."
+
+# JSON output for scripting
+fcht-agent --json run "List skills in memory/skills"
+# {"result": "...", "episodes_added": 1, "steps_taken": 2, "success": true}
+```
+
+### Daemon Mode (Fast, Model Stays Loaded)
+```bash
+# Terminal 1: start daemon
+fcht-agent-daemon
+# {"jsonrpc": "2.0", "method": "ready", "params": {"model": "qwen2.5:7b"}}
+
+# Terminal 2: send requests
+echo '{"task": "What is the project name?", "id": "req-1"}' | fcht-agent-daemon
+# {"id": "req-1", "result": {"output": "...", "episodes_added": 1, "steps_taken": 2, "success": true}}
+```
+
+---
+
+## 🧠 Memory Architecture
+
+```
+memory/
+├── episodes.jsonl          # Episodic: few-shot conversation history
+├── chroma/                 # Semantic: ChromaDB vector store
+│   ├── chroma.sqlite3
+│   └── ...
+└── skills/                 # Procedural: learned Python tools
+    ├── hello.py
+    ├── greeting.py
+    └── fibonacci.py
+```
+
+| Memory Type | Storage | Use Case |
+|-------------|---------|----------|
+| **Episodic** | JSONL (append-only) | Few-shot prompting, conversation continuity |
+| **Semantic** | ChromaDB + embeddings | Fact retrieval, RAG, similarity search |
+| **Procedural** | Python files in `skills/` | Learned procedures, reusable tools |
+
+---
+
+## 🛠 Built-in Tools
+
+| Tool | Description | Example |
+|------|-------------|---------|
+| `shell` | Run shell commands | `{"tool": "shell", "args": {"cmd": "ls -la"}}` |
+| `read_file` | Read file contents | `{"tool": "read_file", "args": {"path": "config.yaml"}}` |
+| `write_file` | Write file contents | `{"tool": "write_file", "args": {"path": "out.py", "content": "print(1)"}}` |
+| `python_exec` | Execute Python code | `{"tool": "python_exec", "args": {"code": "print(2+2)"}}` |
+| `list_files` | List directory | `{"tool": "list_files", "args": {"path": "memory/skills"}}` |
+| `remember` | Store in semantic memory | `{"tool": "remember", "args": {"text": "API key is xyz", "metadata": {"type": "secret"}}}` |
+| `retrieve` | Search semantic memory | `{"tool": "retrieve", "args": {"query": "API key", "n_results": 3}}` |
+
+---
+
+## ⚙️ Configuration
+
+### YAML Config (`config.yaml`)
+```yaml
+ollama:
+  host: "http://localhost:11434"
+  model: "qwen2.5:7b"
+  temperature: 0.1
+  timeout: 120
+
+memory:
+  episodes_path: "memory/episodes.jsonl"
+  max_few_shot: 3
+  chroma_path: "memory/chroma"
+  embed_model: "all-MiniLM-L6-v2"
+  embed_cache_dir: "~/.cache/fcht-agent/embeddings"
+
+agent:
+  max_steps: 10
+  system_prompt: |
+    You are a precise, helpful assistant. Use tools to accomplish tasks.
+    Output ONLY JSON tool calls. When done, respond with 'DONE: <result>'.
+
+daemon:
+  enabled: true
+  host: "127.0.0.1"
+  port: 8765
+```
+
+### Environment Variables (override any setting)
+```bash
+FCHT_OLLAMA__MODEL=llama3.1
+FCHT_MEMORY__MAX_FEW_SHOT=5
+FCHT_AGENT__MAX_STEPS=15
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Memory tests
+pytest tests/test_memory.py -v
+
+# Agent tests
+pytest tests/test_agent.py -v
+```
+
+---
+
+## 📦 Project Structure
+```
+fcht_agent/
+├── __init__.py              # Exports: FCHTAgent, AgentConfig, __version__
+├── config/schema.py         # Pydantic settings (YAML/env/file)
+├── core/agent.py            # ReAct loop + Ollama client + tools
+├── memory/
+│   ├── episodic.py          # JSONL few-shot memory
+│   ├── semantic.py          # ChromaDB + cached embeddings
+│   └── embeddings.py        # Singleton embedding model
+├── tools/registry.py        # 7 built-in tools
+├── cli/main.py              # argparse CLI: run, config, doctor, version
+├── daemon/server.py         # JSON-RPC stdin/stdout daemon
+tests/
+├── test_memory.py           # Memory module tests
+├── test_agent.py            # Agent integration tests
+setup.py                     # Setuptools config
+```
+
+---
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repo
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure `pytest tests/` passes
+5. Submit PR
+
+---
+
+## 🙋 Support
+
+- **Issues**: GitHub Issues
+- **Discussions**: GitHub Discussions
+- **Security**: security@example.com (PGP key available)
+
+---
+
+*Built with ❤️ for local-first AI. Runs on a GTX 1080 Ti (11GB) with qwen2.5:7b.*

fcht_agent-0.1.0/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__"]