Use Cases

These use cases describe what AgenticLocal can do now, plus where the current architecture is meant to grow.

1. Local Workspace Assistant

Use the agent to inspect files, read notes, write safe outputs, and summarize project artifacts inside a configured workspace.

python3 -m agentic_loop "List files in the workspace."
python3 -m agentic_loop "Read notes/example.txt and summarize it."
python3 -m agentic_loop "Write a note saying hello from the agent."

Why it matters:

• File reads stay inside configured read roots.
• Writes default to outputs/.
• Extra write roots are explicit through --write-root.
• Symlink/path escape attempts are denied.

2. Dataset Triage

Inspect CSV data before writing analysis code.

python3 -m agentic_loop "Inspect data/sample.csv as a dataset."

Current behavior:

• Reads CSV headers and rows.
• Counts missing values.
• Detects fully numeric column ranges.
• Emits structured step data when --json is used.

3. Durable Chat And Memory

Use SQLite-backed sessions and long-term memory across runs.

python3 -m agentic_loop --db /tmp/agentic.db "Remember project language is python."
python3 -m agentic_loop --db /tmp/agentic.db "What is the project language?"

Memory split:

• Short-term context: messages sent to the model for the current turn.
• Working memory: run steps and AgentState.
• Session memory: transcript persisted by session_id.
• Long-term memory: deliberate remember/recall facts.
• Retrieval memory: future searchable project/code/docs chunks.

4. Self-Improving Local Skills

Let the runtime summarize completed runs, propose draft learning artifacts, and reuse only approved procedural skills later.

python3 -m agentic_loop chat --learning draft

Inside chat:

/learn
/learn approve ID
/skills
/skill KEY

Current behavior:

• Each completed run can create a sanitized experiences row.
• Repeatable successful tool patterns become draft procedural skills after the configured threshold.
• Drafts stay inactive until approved.
• Approved skill metadata is matched lexically; full skill Markdown is injected only when relevant to the current goal.
• Skill use success/failure is recorded for later review and archiving.

5. Research And News Assistant

Opt into public network tools when you want live information.

python3 -m agentic_loop chat --enable-network-tools

Try:

Search news about robotics.
Search the internet for agentic AI.
Fetch https://example.com and summarize it.

Current tools:

• search_web: DuckDuckGo-backed web search.
• search_news: Google News RSS search.
• fetch_url: HTTP/HTTPS page fetch and text extraction.

The controller protects against repeated identical successful tool calls. If a tool-capable model keeps asking for the same already-completed action, the runtime finalizes from the previous result instead of burning through the step limit.

6. Human-Gated Workspace Changes

Use approval-required roots for outputs that should pause for review.

python3 -m agentic_loop \
  --write-root reviewed \
  --approval-root reviewed \
  "Write a reviewed note."

Current behavior:

• The policy engine marks the write as approval_required.
• The file is not written.
• Events/traces record the approval requirement.

Future UI work can turn that event into an approval modal.

7. Local HTTP Agent Service

Run the same runtime behind HTTP for local apps and dashboards.

python3 -m agentic_loop serve \
  --host 127.0.0.1 \
  --port 8765

Served mode enables public web/news/fetch tools by default. Use --disable-network-tools for a narrower local service.

Useful workflows:

• POST /chat for stateful conversations.
• POST /run for one-shot jobs.
• GET /events for event snapshots.
• GET /events?follow=1&timeout=30 for SSE streaming.
• GET /registry/ui to see component mappings.
• GET /registry/rules and /registry/workflows for toggles and presets.
• GET /registry/models to discover provider/model selection requirements.
• GET /voice for the browser speech page.
• GET /voice/config for realtime voice availability.
• POST /voice/gemini/token to mint a short-lived Gemini Live browser token.
• GET /learning/drafts and GET /skills for learning review.
• POST /learning/drafts/approve and POST /skills/archive for approval and hygiene.

8. Rules, Workflows, And UI Registry

The storage layer persists tool, UI, rule, and workflow registry metadata.

Examples:

• inspect_csv maps to table_preview.
• list_files maps to file_browser.
• remember and recall map to memory_view.
• Network searches map to search/news result components.
• Approval-required events can map to an approval modal.
• max_effort, academic, concise, and safe_writes are toggleable rules.
• /loop, /search, and /release are workflow presets.

This lets a frontend render the same runtime events as a timeline, table preview, file browser, memory view, modal, rule toggle, or workflow button without hardcoding every tool in the page.

9. Voice Companion Around The Same Runtime

The browser voice page currently uses:

Gemini Live mic/audio -> POST /chat -> Gemini Live spoken reply

When Gemini credentials are missing or the browser does not support the needed audio/WebSocket APIs, it falls back to:

Browser Web Speech API -> POST /chat -> browser speech synthesis

The core architecture keeps voice as an adapter boundary, so realtime providers sit around the same policy, tools, memory, and trace system.

Documented provider examples:

• Gemini Live Voice.
• OpenAI Realtime.

10. Provider-Swappable Brain

The model interface is provider-neutral.

Current paths:

• rule: deterministic local planner for tests and demos.
• ollama: local model adapter selected with an explicit model name.
• openai: OpenAI chat-completions-compatible endpoint.
• openai-compatible: API-key-backed compatible endpoint.
• gemini: Gemini or Google-compatible OpenAI-style endpoint with configured api_base.
• localai: LocalAI-compatible endpoint.

Example Ollama run:

python3 -m agentic_loop chat \
  --provider ollama \
  --model gemma4:e4b \
  --enable-network-tools

Or switch inside an interactive chat session:

/models
/model ollama qwen3.5:4b-mlx

Interactive chat defaults to Ollama qwen3.5:4b-mlx. The rule provider is still available for deterministic offline tests and demos. Missing Ollama startup models selected by default or with --model, plus interactive /model switches, prompt for a download before terminal entry points use them.

Served runs can choose the provider/model per request:

curl -s -X POST http://127.0.0.1:8765/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"hello","model":{"provider":"ollama","name":"your-local-model"}}'

11. Research Product Direction

The natural next product shape is a local-first research workspace:

• Search papers and datasets.
• Fetch and snapshot sources.
• Inspect downloaded tables.
• Validate equations and assumptions.
• Keep provenance on every result.
• Stream tool progress into a timeline.
• Let users approve downloads, writes, and trusted-source transitions.

The current runtime already has the main spine for that direction: policy, tools, events, durable state, registries, and provider adapters.