refactor: Refactor the project's docs, scripts, and instructions, and add CI

.env.example

@@ -42,6 +42,7 @@ RETRY_INITIAL_DELAY=1.0        # Initial delay in seconds
 RETRY_MAX_DELAY=60.0           # Maximum delay in seconds
 
 # Memory Management Configuration
+MEMORY_ENABLED=true                   # Enable/disable memory compression
 MEMORY_MAX_CONTEXT_TOKENS=100000       # Maximum context window size
 MEMORY_TARGET_TOKENS=30000             # Target working memory size (soft limit)
 MEMORY_COMPRESSION_THRESHOLD=25000     # Hard limit - compress when exceeded

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v3
+      - name: Bootstrap
+        run: ./scripts/bootstrap.sh --no-env
+      - name: Lint (pre-commit)
+        run: ./scripts/dev.sh precommit
+      - name: Tests
+        run: ./scripts/dev.sh test -q
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v3
+      - name: Bootstrap
+        run: ./scripts/bootstrap.sh --no-env
+      - name: Typecheck
+        run: TYPECHECK_STRICT=1 ./scripts/dev.sh typecheck

.gitignore

@@ -145,6 +145,15 @@ ENV/
 env.bak/
 venv.bak/
 
+# Runtime data (SQLite memory DB, etc.)
+data/
+
+# Claude Code local rules/state (project-local)
+.claude/
+
+# Tool caches
+.AgenticLoop/
+
 # Spyder project settings
 .spyderproject
 .spyproject
@@ -183,9 +192,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 

.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/psf/black
+    rev: 25.1.0
+    hooks:
+      - id: black
+        language_version: python3
+
+  - repo: https://github.com/PyCQA/isort
+    rev: 6.0.0
+    hooks:
+      - id: isort
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: ["--fix"]

AGENTS.md

@@ -0,0 +1,129 @@
+# AgenticLoop — Agent Instructions
+
+This file defines the **operational workflow** for making changes in this repo (how to set up, run, test, format, build, and publish). Keep it short, specific, and executable; link to docs for long explanations.
+
+Prerequisites: Python 3.12+ and `uv` (https://github.com/astral-sh/uv).
+
+## Quickstart (Local Dev)
+
+```bash
+./scripts/bootstrap.sh
+source .venv/bin/activate
+./scripts/dev.sh test
+```
+
+Optional (recommended): enable git hooks:
+
+```bash
+pre-commit install
+```
+
+## CI
+
+GitHub Actions runs `./scripts/dev.sh precommit`, `./scripts/dev.sh test -q`, and strict typecheck on PRs.
+
+## Review Checklist
+
+Run these before concluding a change:
+
+```bash
+./scripts/dev.sh precommit
+TYPECHECK_STRICT=1 ./scripts/dev.sh typecheck
+./scripts/dev.sh test -q
+```
+
+Manual doc/workflow checks:
+- README/AGENTS/docs: avoid legacy/removed commands (`LLM_PROVIDER`, `pip install -e`, `requirements.txt`, `setup.py`)
+- Docker examples use `--mode`/`--task`
+- Python 3.12+ + uv-only prerequisites documented consistently
+
+Change impact reminders:
+- CLI changes → update `README.md`, `docs/examples.md`
+- Config changes → update `.env.example`, `docs/configuration.md`
+- Workflow scripts → update `AGENTS.md`, `docs/packaging.md`
+
+Run a quick smoke task (requires a configured provider in `.env`):
+
+```bash
+python main.py --task "Calculate 1+1"
+```
+
+## Repo Map
+
+- `main.py`, `cli.py`, `interactive.py`: CLI entry points and UX
+- `agent/`: agent loops (ReAct, Plan-Execute) and orchestration
+- `tools/`: tool implementations (file ops, shell, web search, etc.)
+- `llm/`: provider adapters + retry logic
+- `memory/`: memory manager, compression, persistence
+- `docs/`: user/developer documentation
+- `scripts/`: packaging/publishing scripts
+- `test/`: tests (some require API keys; memory tests are mostly mocked)
+
+## Commands (Golden Path)
+
+### Install
+
+- Use `./scripts/bootstrap.sh` to create `.venv` and install dependencies.
+- Use `./scripts/dev.sh install` to reinstall dev deps into an existing `.venv`.
+
+### Tests
+
+- All tests: `python -m pytest test/`
+- Memory suite: `python -m pytest test/memory/ -v`
+- Script: `./scripts/test.sh`
+- Unified entrypoint: `./scripts/dev.sh test`
+- Integration tests: set `RUN_INTEGRATION_TESTS=1` (live LLM; may incur cost)
+
+### Format
+
+This repo uses `black` + `isort` (see `pyproject.toml`).
+
+```bash
+python -m black .
+python -m isort .
+```
+
+Script: `./scripts/format.sh`
+Unified entrypoint: `./scripts/dev.sh format`
+
+### Lint / Typecheck
+
+- Lint (format check): `./scripts/dev.sh lint`
+- Pre-commit (recommended): `./scripts/dev.sh precommit`
+- Typecheck (best-effort): `./scripts/dev.sh typecheck` (set `TYPECHECK_STRICT=1` to fail on errors)
+
+### Build (Packaging)
+
+```bash
+./scripts/build.sh
+```
+Unified entrypoint: `./scripts/dev.sh build`
+
+### Publish (Manual / Interactive)
+
+`./scripts/publish.sh` defaults to an interactive confirmation and refuses to run without a TTY unless you pass `--yes`.
+
+- TestPyPI: `./scripts/publish.sh --test`
+- PyPI (manual): `./scripts/publish.sh`
+- Unified entrypoint: `./scripts/dev.sh publish`
+
+## Docs Pointers
+
+- Configuration & `.env`: `docs/configuration.md`
+- Packaging & release checklist: `docs/packaging.md`
+- Extending tools/agents: `docs/extending.md`
+- Memory system: `docs/memory-management.md`, `docs/memory_persistence.md`
+- Usage examples: `docs/examples.md`
+
+## Safety & Secrets
+
+- Never commit `.env` or API keys.
+- Avoid running destructive shell commands; keep file edits scoped and reversible.
+- Publishing/releasing steps require explicit human intent (see `docs/packaging.md`).
+
+## When Changing Key Areas
+
+- If you change CLI flags / behavior: update `README.md` and `docs/examples.md`.
+- If you change configuration/env vars: update `docs/configuration.md` and `.env.example`.
+- If you change packaging/versioning: update `pyproject.toml` and `docs/packaging.md`.
+- If you change memory/compression/persistence: add/adjust tests under `test/memory/` and update `docs/memory-management.md` / `docs/memory_persistence.md`.

Dockerfile

@@ -10,13 +10,13 @@ RUN apt-get update && apt-get install -y \
     git \
     && rm -rf /var/lib/apt/lists/*
 
-# Copy requirements first for better caching
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-
 # Copy application code
 COPY . .
 
+# Install uv and package dependencies
+RUN pip install --no-cache-dir uv
+RUN uv pip install --system .
+
 # Create a non-root user
 RUN useradd -m -u 1000 agentuser && chown -R agentuser:agentuser /app
 USER agentuser
@@ -31,4 +31,4 @@ CMD ["--help"]
 
 # Usage:
 # Build: docker build -t AgenticLoop .
-# Run: docker run -it --rm -e ANTHROPIC_API_KEY=your_key AgenticLoop interactive
+# Run: docker run -it --rm -e ANTHROPIC_API_KEY=your_key AgenticLoop --mode react --task "Hello"

MANIFEST.in

@@ -2,6 +2,5 @@
 include README.md
 include LICENSE
 include .env.example
-include requirements.txt
 recursive-include docs *.md
 recursive-include examples *.py *.md

README.md

@@ -4,6 +4,10 @@ General AI Agent System
 
 ## Installation
 
+Prerequisites for development:
+- Python 3.12+
+- `uv` (https://github.com/astral-sh/uv)
+
 ### Option 1: Install from PyPI (Recommended - Coming Soon)
 
 ```bash
@@ -17,8 +21,8 @@ pip install AgenticLoop
 git clone https://github.com/yourusername/AgenticLoop.git
 cd AgenticLoop
 
-# Install in development mode
-pip install -e .
+# Bootstrap (recommended)
+./scripts/bootstrap.sh
 ```
 
 ### Option 3: Install from GitHub
@@ -31,11 +35,26 @@ pip install git+https://github.com/yourusername/AgenticLoop.git
 
 ```bash
 docker pull yourusername/AgenticLoop:latest
-docker run -it --rm -e ANTHROPIC_API_KEY=your_key AgenticLoop interactive
+docker run -it --rm -e ANTHROPIC_API_KEY=your_key AgenticLoop --mode react
 ```
 
 ## Quick Start
 
+For repo workflow (install/test/format/build/publish), see `AGENTS.md`.
+
+### 0. Install Dependencies (Recommended)
+
+```bash
+./scripts/bootstrap.sh
+```
+
+Optional (recommended): enable git hooks for consistent formatting/linting on commit:
+
+```bash
+source .venv/bin/activate
+pre-commit install
+```
+
 ### 1. Configuration
 
 Create `.env` file:
@@ -49,7 +68,7 @@ Edit `.env` file and configure your LLM provider:
 ```bash
 # LiteLLM Model Configuration (supports 100+ providers)
 # Format: provider/model_name
-LITELLM_MODEL=anthropic/claude-3-5-sonnet
+LITELLM_MODEL=anthropic/claude-3-5-sonnet-20241022
 
 # API Keys (set the key for your chosen provider)
 ANTHROPIC_API_KEY=your_anthropic_api_key_here
@@ -67,6 +86,7 @@ LITELLM_TIMEOUT=600            # Request timeout in seconds
 MAX_ITERATIONS=100  # Maximum iteration loops
 
 # Memory Management
+MEMORY_ENABLED=true
 MEMORY_MAX_CONTEXT_TOKENS=100000
 MEMORY_TARGET_TOKENS=30000
 MEMORY_COMPRESSION_THRESHOLD=25000
@@ -87,7 +107,7 @@ LOG_TO_CONSOLE=false
 
 **Quick setup for different providers:**
 
-- **Anthropic Claude**: `LITELLM_MODEL=anthropic/claude-3-5-sonnet`
+- **Anthropic Claude**: `LITELLM_MODEL=anthropic/claude-3-5-sonnet-20241022`
 - **OpenAI GPT**: `LITELLM_MODEL=openai/gpt-4o`
 - **Google Gemini**: `LITELLM_MODEL=gemini/gemini-1.5-pro`
 - **Azure OpenAI**: `LITELLM_MODEL=azure/gpt-4`
@@ -105,10 +125,10 @@ See [LiteLLM Providers](https://docs.litellm.ai/docs/providers) for 100+ support
 aloop
 
 # Single task (ReAct mode)
-aloop --mode react "Calculate 123 * 456"
+aloop --mode react --task "Calculate 123 * 456"
 
 # Single task (Plan-Execute mode)
-aloop --mode plan "Build a web scraper"
+aloop --mode plan --task "Build a web scraper"
 
 # Show help
 aloop --help
@@ -166,7 +186,6 @@ See [Memory Management Documentation](docs/memory-management.md) for detailed in
 ```
 AgenticLoop/
 ├── README.md                    # This document
-├── requirements.txt             # Python dependencies
 ├── .env.example                 # Environment variables template
 ├── config.py                    # Configuration management
 ├── main.py                      # CLI entry point
@@ -225,7 +244,7 @@ See the full configuration template in `.env.example`. Key options:
 
 | Setting | Description | Default |
 |---------|-------------|---------|
-| `LITELLM_MODEL` | LiteLLM model (provider/model format) | `anthropic/claude-3-5-sonnet` |
+| `LITELLM_MODEL` | LiteLLM model (provider/model format) | `anthropic/claude-3-5-sonnet-20241022` |
 | `LITELLM_API_BASE` | Custom base URL for proxies | Empty |
 | `LITELLM_DROP_PARAMS` | Drop unsupported params | `true` |
 | `LITELLM_TIMEOUT` | Request timeout in seconds | `600` |
@@ -244,8 +263,9 @@ See [Configuration Guide](docs/configuration.md) for detailed options.
 Run basic tests:
 
 ```bash
-source venv/bin/activate
-python test_basic.py
+./scripts/bootstrap.sh
+source .venv/bin/activate
+./scripts/dev.sh test -q
 ```
 
 ## Learning Resources
@@ -288,14 +308,14 @@ See the [Packaging Guide](docs/packaging.md) for instructions on:
 
 Quick commands:
 ```bash
-# Install locally for development
-./scripts/install_local.sh
+# Bootstrap local dev environment (creates .venv, installs deps, initializes .env)
+./scripts/bootstrap.sh
 
 # Build distribution packages
-./scripts/build.sh
+./scripts/dev.sh build
 
 # Publish to PyPI
-./scripts/publish.sh
+./scripts/dev.sh publish
 ```
 
 ## Contributing