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.*
