░▒▓██████▓▒░░▒▓████████▓▒░▒▓████████▓▒░▒▓████████▓▒░▒▓███████▓▒░  
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░      ░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░ 
░▒▓█▓▒░░▒▓█▓▒░      ░▒▓█▓▒░    ░▒▓██▓▒░░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░ 
░▒▓████████▓▒░     ░▒▓█▓▒░   ░▒▓██▓▒░  ░▒▓██████▓▒░ ░▒▓█▓▒░░▒▓█▓▒░ 
░▒▓█▓▒░░▒▓█▓▒░     ░▒▓█▓▒░ ░▒▓██▓▒░    ░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░ 
░▒▓█▓▒░░▒▓█▓▒░    ░▒▓█▓▒░ ░▒▓█▓▒░      ░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░ 
░▒▓█▓▒░░▒▓█▓▒░    ░▒▓█▓▒░ ░▒▓████████▓▒░▒▓████████▓▒░▒▓███████▓▒░  

a7_zed

a7_zed is a Rust-first, prompt-driven agentic framework. The runtime ships as Cargo crates under crates/, while Markdown and static assets (prompts/, agents/, webui/, knowledge/, conf/, fixtures/) remain the canonical source for behavior copy, UI bundling, and provider configuration.

This README focuses on how the system fits together, what the Rust rewrite changed, and how to operate it day to day.

---

Main dashboard

The web UI home screen (sidebar, sessions, and landing view):

---

Main chat window

The web UI during an active chat (transcript, structured responses, and composer):

---

Table of contents

1. Main dashboard
2. Main chat window
3. What changed with Rust development
4. Architecture at a glance
5. Workspace map
6. Quick start
7. Configuration & embeddings
8. Docker
9. Development workflow
10. Further reading

---

What changed with Rust development

The project was cut over from an in-repo Python application stack to a native Rust workspace. The bullets below summarize the contract you should assume when reading issues, PRs, or older docs.

Runtime

Before (legacy)	After (Rust-first)
Python launcher, LiteLLM-style wiring in-process	cargo run -p a7-web launches the Axum server and agent runtime
Python models/prompt/helpers	a7-core (AgentRuntime, PromptLoader), a7-models (HTTP chat + provider resolution), a7-tools
Mixed test stories	cargo test --workspace; migration-sensitive checks via a7-migration + a7-memory

Source tree

Removed / retired from source	Replaced by
Root Python entrypoints and runtime modules	Crates a7-web, a7-core, a7-models, a7-memory, a7-tools, a7-api
Python prompt variable plugins	Rust PromptLoader generates variables such as {{tools}} and {{agent_profiles}} from Markdown
Python-native dependency manifests as the app driver	Cargo workspace (Cargo.toml)

Behavioral expectations

Topic	Rust behavior today
Routes & tools	Legacy HTTP routes exist for UI compatibility and are classified through crates/a7-api; incomplete retained behavior must be marked Stubbed and return explicit stub JSON.
Docker	Current Docker builds aim to run the Rust a7-web binary (docker/run); legacy scripts elsewhere may still mention older launchers (AGENTS.md).
MCP, browser automation, some automation hooks	May be stubs or partially implemented; speech routes are Groq-backed when GROQ_API_KEY is configured. See docs/rust-rewrite/NATIVE_PROGRESS.md.

Optional local embedding sidecars are supported via OpenAI-compatible POST .../embeddings: when api_base targets loopback (127.0.0.1 / localhost / IPv6 loopback), the memory client omits Authorization if no {PROVIDER}_API_KEY is set. LAN-only hosts require A7_EMBEDDING_ALLOW_NO_AUTH (trusted networks only); see conf/model_providers.yaml local_sidecar entry.

---

Architecture at a glance

Logical request flow (chat)

flowchart LR
  subgraph client [Browser]
    UI["webui/ static assets"]
  end
  subgraph server [crates/a7-web]
    Axum["Axum router + middleware"]
    State["SharedState (sessions, memory, runtime)"]
  end
  subgraph runtime [Agent loop]
    AR["AgentRuntime"]
    TL["Tools (a7-tools)"]
    PL["PromptLoader (a7-core)"]
  end
  subgraph models [Models]
    HM["HttpChatModel / UnifiedChatModel (a7-models)"]
    Endpoint["Resolved endpoint (YAML + tmp/settings.json)"]
  end
  UI --> Axum --> State --> AR
  AR --> PL
  AR --> TL
  AR --> HM --> Endpoint

Loading

Memory search and embeddings

flowchart TB
  subgraph mem [crates/a7-memory]
    SQL["SQLite store (documents + optional vectors)"]
    HTTP["HttpEmbeddingClient"]
    RES["Resolve endpoint (YAML + settings)"]
  end
  subgraph remote [Outbound HTTP]
    Sidecar["Local sidecar OpenAI /v1/embeddings"]
    Cloud["OpenAI-compatible or HuggingFace inference API"]
  end
  SQL --> HTTP --> RES
  HTTP --> Sidecar
  HTTP --> Cloud

Loading

Crate responsibilities (simplified dependency story)

graph TB
  a7_web["a7-web"]
  a7_core["a7-core"]
  a7_models["a7-models"]
  a7_memory["a7-memory"]
  a7_tools["a7-tools"]
  a7_api["a7-api"]
  a7_migration["a7-migration"]
  a7_preload["a7-preload"]
  assets["Markdown & static assets
(prompts/, agents/, webui/, ...)"]
  a7_web --> a7_core
  a7_web --> a7_models
  a7_web --> a7_memory
  a7_web --> a7_tools
  a7_web --> a7_api
  a7_web --> a7_preload
  a7_core --> assets

Loading

---

Workspace map

Crate / path	Role
crates/a7-web	Axum server: API routes retained for UI parity, auth/CSRF session shape, hosts webui/
crates/a7-core	Agent runtime semantics, PromptLoader, persistence contracts surfaced to tools
crates/a7-models	Chat over HTTP (/chat/completions, Anthropic /messages), provider YAML resolution, embedding bearer resolution helpers
crates/a7-memory	SQLite-backed memory, optional embedding HTTP fan-out, migration import tooling
crates/a7-tools	Native tools (response, timers, filesystem hooks where implemented, stubs where not)
crates/a7-api	Route inventory plus stub vs native labeling for API contracts
crates/a7-preload	Startup preload/reporting scaffolding used from a7-web
crates/a7-migration	Legacy layout validation and cutover readiness
crates/a7-desktop-spike	Experimental desktop spike (workspace member; not primary server)
prompts/, agents/	Behavioral Markdown; profile overlays under agents/<profile>/prompts/ (baseline files live under agents/default/; saved legacy IDs agent0 / _internal load as default)
conf/model_providers.yaml	Canonical provider IDs, default API bases (chat + embedding), extra headers

---

Quick start

Run the Rust web UI (defaults 127.0.0.1:5000, serves static UI from webui/):

cargo run -p a7-web

Bind on all interfaces and change port:

WEB_UI_HOST=0.0.0.0 WEB_UI_PORT=50001 cargo run -p a7-web

Minimal mental model for operators

1. Secrets: prefer environment variables keyed by provider (for example GROQ_API_KEY, OPENAI_API_KEY, HUGGINGFACE_API_KEY), matching conf/model_providers.yaml conventions. For the native search_engine tool, optional SERPAPI_API_KEY (or API_KEY_SERPAPI) enables SerpApi; without it, configure SearxNG via SEARXNG_URL.
2. Settings: tmp/settings.json is the persisted UI/runtime settings blob the server reads alongside env overrides.
3. Memory DB: A7_MEMORY_DB selects the SQLite file; otherwise memory/rust_native/memory.sqlite under the crate working tree layout applies.

---

Configuration & embeddings

Provider YAML

conf/model_providers.yaml lists embedding providers such as openai, ollama, lm_studio, huggingface, and local_sidecar (OpenAI-compatible /v1/embeddings on **http://127.0.0.1:8080/v1 by default, overridable through settings).

Embedding environment shortcuts

Variable	Meaning
A7_MEMORY_EMBED_BASE	Base URL fragment for embeddings when using from_env path in tooling
A7_MEMORY_EMBED_MODEL	Model id for embeddings in that env path
A7_MEMORY_EMBED_API_KEY	Optional dedicated key (overrides provider-id discovery for that env path)
A7_EMBEDDING_ALLOW_NO_AUTH	When truthy (1, true, yes, on), allow unauthenticated embedding HTTP (LAN only, trusted networks).

Bearer resolution order is implemented in a7-models and consumed by a7-memory: explicit memory-env key, then {PROVIDER}_API_KEY-style aliases, then anonymous allowed when loopback (or insecure override).

---

Docker

The Docker slice under docker/run builds/runs a7-web:

docker build -f docker/run/Dockerfile -t a7-zed:rust .
docker run --rm -p 50080:5000 -e GROQ_API_KEY -e HUGGINGFACE_API_KEY a7-zed:rust

Or compose:

docker compose -f docker/run/docker-compose.yml up --build

---

Development workflow

Formatting and workspace tests:

cargo fmt --all
cargo test --workspace

Focused crates while iterating:

cargo test -p a7-core
cargo test -p a7-web
cargo test -p a7-models -p a7-memory -p a7-migration

---

Further reading

Document	Content
AGENTS.md	Crate boundaries, testing expectations, stubs policy
docs/rust-rewrite/NATIVE_PROGRESS.md	Native vs stubbed surface area ledger
docs/quickstart.md	Faster onboarding-focused steps
docs/troubleshooting.md	Common fixes (providers, local models)

Secrets must never be committed: keep API keys and tokens out of tmp/ logs pasted into tickets, and scrub .env before sharing bundles.