acchite.md

2. System Components

2.1 User Interface

• Streamlit-based web UI.

• Features:

  • Prompt input
  • /HELP commands
  • Code generation /WRITE_PY
  • Code editing + execution (CPU or optional GPU)
  • Book, story, or poem management
  • Session logs and downloads

---

2.2 Agent Core — pygmyclaw.py

• Handles all user-agent interaction:

  • Receives user prompts.
  • Converts LLM output into JSON tool calls.
  • Dynamically loads and executes Python tools.

• Speculative decoding:

  • 3 drafters + 1 verifier for robust output.

• Queue system:

  • Redis or JSON-file queue for task scheduling.

• Artifact management:

  • Stores code, logs, and task outputs in workspace.
  • Supports automatic dependency installation.

---

2.3 Python Multitool — pygmyclaw_multitool.py

• Tool registry:

  • list_tools_detailed, sys_info, log_error, echo, etc.

• Dynamic tool addition:

  • Agents can create new tools that are callable via JSON.

• Safe execution sandbox:

  • Python subprocess with controlled input/output.

---

2.4 LLM Interaction

• Ollama / HF-hosted model as backend:

  • Multi-instance support for parallel drafters.
  • Token-based speculative decoding.

• Workflow:

  User prompt
      ↓
  Agent (LLM)
      ↓
  JSON tool call
      ↓
  Python tool executes
      ↓
  Result returned to LLM
      ↓
  Final response to user
  

• Dynamic code generation & execution integrated:

  • e.g., user asks for PyTorch demo → agent installs PyTorch → generates editable code → runs it in UI.

---

2.5 Persistent Memory — Hugging Face

• Repository: rahul7star/pyclaw

• Stores:

  • Generated code & scripts
  • Task outputs (.out)
  • Logs & session history
  • Dynamic tools and metadata

• Mechanism:

  • Push artifacts via huggingface_hub API
  • Pull existing artifacts for agent memory

• Benefits: Enables long-term learning, cross-session continuity, and reproducibility.

---

2.6 Autonomous Task Management

• Queue-based execution:

  • Tasks added by user or agent itself.
  • Background processor executes tasks in order.

• Speculative execution:

  • Multi-instance drafters improve code reliability.
  • Verifier ensures correctness of outputs.

• Dynamic tools:

  • Tools can evolve or new tools can be created on-the-fly.

---

2.7 Safety & Resource Management

• Code execution sandbox:

  • Controlled Python subprocess.
  • Auto cleanup of temporary files.

• CPU/GPU selection:

  • Default: CPU
  • Optional: GPU if available and environment variable set.

• Dependency management:

  • Automatic package installation (e.g., PyTorch for user-requested demos).

---

3. Example User Workflow

User Prompt: "Create a neural network demo in Python using PyTorch."

Agent Actions:

1. Detects PyTorch requirement → installs on CPU.
2. Generates Python code using /WRITE_PY.
3. Saves code in Hugging Face repo for memory.
4. Displays code in UI for editing.
5. Runs code → outputs printed and logged.
6. Updates agent memory with results and execution logs.
7. Optionally creates a new dynamic tool for future NN generation.

---

4. Evolvable Architecture

Feature	Current Status	Future Evolution
Dynamic Tool Creation	✅	Can auto-generate new tools from tasks
Long-Term Memory	✅ via HF	Add semantic search, embeddings for context
Speculative Decoding	✅	Increase drafters, multi-agent cooperation
Autonomous Task Execution	Partial	Recursive task planning, multi-step project handling
Dependency Management	✅	Expand to virtual environments per project
Safe Execution	Partial	Containerized execution (Docker/WSL)

---

5. Roadmap to Claude-Like Autonomy

1. Enhance memory: Semantic embeddings + search in HF repo.
2. Recursive reasoning: Agent generates subtasks autonomously.
3. Multi-agent collaboration: Multiple PygmyClaws coordinate on large projects.
4. Learning from outputs: Store completed tasks + feedback for continuous improvement.
5. Safety & isolation: Dockerized Python execution with resource limits.
6. Dynamic UI: Allow live editing, execution, and visualization of code outputs.

---

6. Diagram of End-to-End Flow

           ┌───────────────┐
           │   User Prompt │
           └───────┬───────┘
                   │
                   ▼
           ┌───────────────┐
           │  Agent (LLM)  │
           └───────┬───────┘
                   │ JSON Tool Call
                   ▼
           ┌───────────────┐
           │ Python Tool   │
           │ Executes Task │
           └───────┬───────┘
                   │ Result
                   ▼
           ┌───────────────┐
           │  Agent (LLM)  │
           │ Processes     │
           └───────┬───────┘
                   │
                   ▼
           ┌───────────────┐
           │   UI Output   │
           │ (Code/Result) │
           └───────┬───────┘
                   │
                   ▼
           ┌───────────────┐
           │ │
           │ Persistent    │
           │ Memory Repo   │
           └───────────────┘

---