AZME Workspace
==============

AZME is a multi-engine AI platform that combines neural inference, symbolic reasoning, memory, agents, monitoring, and workflow orchestration in one Rust-first workspace.

This repository was recovered and stabilized from a paused state. It now provides a real execution baseline that compiles, starts, and exposes operational APIs, with strict error behavior when model/runtime dependencies are unavailable.

Why this project exists
-----------------------

Modern AI systems are usually fragmented into isolated services. AZME aims to provide a single architecture where these capabilities work together:

* Neural generation and inference
* Symbolic reasoning (AZL runtime)
* Memory and retrieval
* Agent coordination
* Monitoring and operational observability
* Workflow execution across subsystems

Current status (March 2026)
---------------------------

The project is in production-oriented foundation stage:

* Workspace builds and checks pass for the active crates
* API runtime is operational and reports subsystem readiness honestly
* AGI CLI loop control is wired and usable
* Deployment scripts are aligned with current Rust binaries
* Neural inference path is in strict mode (no fake fallback text)

What is still being completed:

* Full real-model runtime compatibility for local Qwen artifacts and quantization toolchain
* Contract normalization across crates (monitoring/task/metrics types)
* Wider end-to-end integration tests and contributor automation

Quick start
-----------

1) Validate Rust workspace

.. code-block:: bash

   cd crates
   cargo check -p azme-core -p azme-api -p azme-neural -p azme-memory -p azme-agents

2) Start API on a free port

.. code-block:: bash

   cd crates
   AZME_API_PORT=18080 cargo run -p azme-api --bin azme-api

3) Probe health and status

.. code-block:: bash

   curl http://localhost:18080/health
   curl http://localhost:18080/status

4) Try generation

.. code-block:: bash

   curl -X POST http://localhost:18080/generate \
     -H "content-type: application/json" \
     -d '{"prompt":"Hello AZME","max_tokens":64,"temperature":0.7}'

If the model is not loaded, the API returns a structured 503 error explaining why, instead of returning synthetic text.

AGI CLI
-------

.. code-block:: bash

   cd crates
   cargo run -p azme-core --bin azme-core -- agi status
   cargo run -p azme-core --bin azme-core -- agi inject "Stabilize contracts" "Unify cross-crate metrics" high

Repository map
--------------

* ``crates/azme-api``: HTTP API and runtime composition
* ``crates/azme-core``: AGI loop and CLI control
* ``crates/azme-neural``: neural engine and model integrations
* ``crates/azme-memory``: memory and knowledge graph
* ``crates/azme-agents``: agent orchestration layer
* ``crates/azme-monitoring``: runtime monitoring and alerts
* ``crates/azme-workflows``: workflow execution
* ``crates/azme-symbolic``: symbolic reasoning / AZL runtime
* ``deployment/``: startup scripts
* ``scripts/``: build and packaging scripts
* ``START_HERE_AZME_RECOVERY.md``: historical recovery context

Next 10 contributor issues
--------------------------

These are concrete, high-impact items for continuation:

1. Unify ``MonitoringSystem`` and ``SystemMetrics`` contracts across crates.
2. Unify ``QuantumOptimizationMetrics`` into one canonical type.
3. Complete sharded safetensors load path in neural runtime.
4. Add model-loading integration tests for strict real-mode inference.
5. Wire API configuration from TOML/env into all runtime subsystems.
6. Add persistent memory backend option (SQLite/Postgres) for ``azme-memory``.
7. Seed default agents at startup and expose agent lifecycle endpoints.
8. Expand workflow-to-agent execution with real task dispatch metrics.
9. Add CI pipeline for lint/check/test matrix on active crates.
10. Reconcile and re-enable ``azme-dashboard`` against current APIs.

If you want to work on one of these, open an issue and mention the item number for fast triage.

Contribution
------------

Please read ``CONTRIBUTING.rst`` before opening a pull request.