Skip to content
sahil-mangla
atlas
Public

About

ATLAS is an AI-native engineering operating system that transforms ideas into production-ready software through structured research, architecture, planning, implementation, verification, and persistent project intelligence.

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

ATLAS

Where Ideas Become Engineering.

Version License: MIT Python 3.13+ CI

ATLAS is an AI-native engineering operating system that transforms ideas into production-ready software through structured research, architecture, planning, implementation, verification, and persistent project intelligence.

Rather than a chat window bolted onto a code editor, ATLAS models software engineering as a disciplined, auditable pipeline: every AI-generated proposal is reviewed and explicitly approved by a human before it becomes part of the project's permanent record. Nothing an AI drafts is ever silently committed.

Table of Contents

What ATLAS Does

Every project moves through the same four-stage engineering pipeline:

  Research  ─────▶  Planning  ─────▶  Architecture  ─────▶  Evaluation
  (problem,          (scope,           (components,          (readiness
   evidence,          milestones,       decisions,            review,
   findings)          tasks)           interfaces)           knowledge)

For each stage, ATLAS:

  1. Generates a draft proposal using your configured AI provider, grounded in the project's accumulated context (prior approved research, plans, and architecture decisions). For the Research stage specifically, evidence is grounded further still: before the AI drafts anything, ATLAS queries real paper sources (arXiv, Semantic Scholar, OpenAlex) and builds each evidence entry's citation and origin directly from that source's own metadata -- never from LLM recall. The AI's only role there is condensing an already-real abstract into a summary; it cannot invent sources.
  2. Presents it for human review -- nothing is written to the project until you decide. Every proposal is also rendered to a plain-Markdown file under atlas-proposals/pending/ in your project root -- readable and reviewable like any other file in your repo, not just as a JSON blob inside a dotfolder.
  3. Commits your decision. Approve it and it becomes a permanent, versioned snapshot -- its Markdown record moves to atlas-proposals/approved/ as a durable, git-diffable trail; reject it with feedback and regenerate.
  4. Extracts durable engineering knowledge from what you approved, so later stages (and later projects) can draw on it.

The result is a project directory (.atlas/) holding a fully traceable history of every research finding, planning decision, architectural choice, and evaluation -- not just the final code, but the reasoning that produced it -- plus a repo-visible atlas-proposals/ folder holding the human-readable record of everything that was proposed and decided.

Quick Start

Prerequisites

Install

From source (recommended until a PyPI release is published):

git clone https://github.com/sahil-mangla/atlas.git
cd atlas
pip install .

Directly from GitHub, without cloning:

pip install git+https://github.com/sahil-mangla/atlas.git

Either way, this installs the atlas command globally in your active Python environment.

atlas version
# ATLAS  1.0.0

Configure

ATLAS reads configuration from environment variables (optionally via a .env file in your working directory). At minimum, set an API key for your chosen provider -- see Configuring an AI Provider below.

export ATLAS_GEMINI_API_KEY="your-api-key-here"

Your First Project

# Create a project
atlas project create --name "My Project" \
  --description "A short description of what this is." \
  --objective "The core goal this project exists to achieve."

# Note the project ID printed above, then check its status
atlas workflow status --project-id <project-id>

# Advance into the Research stage
atlas workflow transition --project-id <project-id> --reason "Starting research."

# Generate an AI research proposal
atlas stage execute --project-id <project-id> --stage research

# Review the generated proposal (printed above), then approve or reject it
atlas proposal approve --project-id <project-id> --proposal-id <proposal-id>
# ...or, to send it back with feedback instead:
atlas proposal reject --project-id <project-id> --proposal-id <proposal-id> \
  --feedback "Needs more evidence on X."

Repeat stage execute / proposal approve for each subsequent AI-assisted stage (planning, architecture, review) as the project progresses. Once the project reaches a human-driven stage with no AI executor (iteration, completion), clear its listed objectives with workflow complete-objective before running workflow transition again -- see Progressing through a human-driven stage.

Each committed stage proposal may also extract engineering-knowledge candidates -- run atlas knowledge list --project-id <project-id> to see them, atlas knowledge show --project-id <project-id> --candidate-id <candidate-id> for full detail, and atlas knowledge approve (publishes) or atlas knowledge reject --feedback <f> to review one.

See the CLI Reference below for the full command set.

Semantic Knowledge Retrieval (optional)

By default, each stage is grounded in the newest published knowledge entries. Set ATLAS_EMBEDDING_ENABLED=true to rank those entries by semantic similarity to the project's objective and your instructions instead, using an embedded sqlite-vec index at .atlas/knowledge.vec.db. The index is a rebuildable cache: published knowledge in .atlas/knowledge.json stays the source of truth, and entries are embedded lazily on first retrieval. If embedding fails, retrieval falls back to newest-first.

ATLAS_EMBEDDING_ENABLED=true
ATLAS_EMBEDDING_MODEL="nomic-embed-text"   # model name for your embedding backend
# Optional; protocol, endpoint and API key default to the ATLAS_AI_* values.
# ATLAS_EMBEDDING_PROTOCOL=OLLAMA
# ATLAS_EMBEDDING_ENDPOINT=http://localhost:11434
# ATLAS_EMBEDDING_API_KEY=...

Embeddings are supported for the GEMINI, OLLAMA and OPENAI_COMPATIBLE protocols; ANTHROPIC has no embeddings API. Search is an exact cosine scan (no ANN index), one vector per entry. See ADR-006.

A labelled retrieval eval lives in evals/retrieval/:

uv run python -m evals.retrieval --model nomic-embed-text   # needs a running Ollama

On its 30 queries over 190 sections of this repo's own docs (a proxy corpus, not reviewed knowledge; queries written by the feature's author), nomic-embed-text gave hit@5 0.90 and MRR@20 0.79, against 0.83 and 0.64 for a BM25 keyword baseline and 0.10 and 0.06 for the previous newest-first behaviour. The advantage over BM25 is small and mostly within bootstrap noise at this sample size. Full numbers are in evals/retrieval/results.json.

Observability and Evaluations

Every envelope-based request handled through Atlas.handle() produces a structured trace containing its capability, adapter, latency, outcome, and AI token usage.

ATLAS features a built-in dual-sink observability layer:

  1. Local Filesystem Sink: Production bootstrap writes daily JSONL traces under <workspace-root>/traces/YYYY-MM-DD.jsonl.
  2. Langfuse Cloud / Self-Hosted Sink: Integrates with Langfuse for production LLM observability, tracking prompt inputs, generation outputs, token usage, cost, and end-to-end request hierarchies.

Configuring Langfuse

To stream traces to Langfuse, provide your keys in .env:

LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_HOST="https://cloud.langfuse.com"  # or your self-hosted instance

Set ATLAS_INSTRUMENTATION_ENABLED=false to disable tracing completely. Unexpected exceptions are traced and re-raised, while exporter failures are non-blocking and never interrupt request handling.

The platform also includes a YAML-driven evaluation suite for command routing, response schemas, multi-step workflows, error handling, and AI execution:

uv run python -m evals

Runs are written to evals/runs/ and compared with the tracked baseline at evals/baselines/latest.json. See the observability guide and evaluation guide for configuration, task authoring, trace fields, and baseline updates.

Configuring an AI Provider

ATLAS is provider-agnostic: it talks to any of four protocols through a common interface, selected via ATLAS_AI_PROTOCOL (defaults to GEMINI). .env.example has a ready-to-uncomment block for each row below, including OpenAI and LM Studio (both are OPENAI_COMPATIBLE targets, not separate protocols).

Protocol Env var(s) Notes
GEMINI ATLAS_GEMINI_API_KEY, ATLAS_GEMINI_MODEL Google's Gemini API. Default provider. Cloud.
ANTHROPIC ATLAS_AI_API_KEY, ATLAS_AI_MODEL Anthropic's Messages API. Cloud.
OPENAI_COMPATIBLE ATLAS_AI_API_KEY, ATLAS_AI_MODEL, ATLAS_AI_ENDPOINT OpenAI itself (cloud), or any OpenAI-compatible endpoint -- including LM Studio's local server (http://localhost:1234/v1, no API key needed). Give the base URL only -- ATLAS appends /chat/completions itself. Endpoint and model are both required; there is no default endpoint.
OLLAMA ATLAS_AI_MODEL, ATLAS_AI_ENDPOINT Local models via Ollama; no API key needed. Endpoint defaults to http://localhost:11434.

All protocols also respect ATLAS_AI_TIMEOUT_SECONDS (default 60, seconds) for the HTTP request timeout. Cloud providers (Gemini, Anthropic, OpenAI) rarely need more than the default. Locally-hosted models (Ollama, LM Studio) generating long structured drafts on modest hardware can take well over a minute -- if you see AI provider timeout errors against a local model, raise this to 180-300.

All settings are read as environment variables prefixed with ATLAS_ (e.g. ATLAS_WORKSPACE_ROOT to change where project directories are created, default ./workspace). Copy .env.example to .env and fill in your values to configure a project directory instead of exporting variables by hand.

CLI Reference

atlas <group> <sub-command> [flags]
Group Command Description
project create --name <n> --description <d> --objective <o> Create a new project workspace
load --project-id <uuid> Load a project's context
list List all known projects
archive --project-id <uuid> Archive an active project
workflow status --project-id <uuid> Show the current stage and readiness
transition --project-id <uuid> --reason <r> Transition to the next stage
complete-objective --project-id <uuid> --objective <o> Clear one active objective on a human-driven stage (problem_definition, implementation, iteration, completion)
stage execute --project-id <uuid> --stage <s> Generate an AI draft for the current stage
proposal approve --project-id <uuid> --proposal-id <uuid> Approve and commit a draft
reject --project-id <uuid> --proposal-id <uuid> --feedback <f> Reject a draft with feedback
knowledge list --project-id <uuid> [--status <s>] List engineering-knowledge candidates
show --project-id <uuid> --candidate-id <uuid> Show one candidate's full content
approve --project-id <uuid> --candidate-id <uuid> Approve and publish a candidate (one step)
reject --project-id <uuid> --candidate-id <uuid> --feedback <f> Reject a candidate with feedback
presentation dashboard|workflow|research|knowledge|diagnostics --project-id <uuid> [--format <f>] Render a composed view to stdout
export --project-id <uuid> --view <v> --output <path> [--format <f>] Render a view to a file

<s> is one of research, planning, architecture, review. <f> (presentation format) is one of cli (default), markdown, json. Full details: docs/usage/cli.md.

Architecture

ATLAS is organized as a strict layered architecture: a stateless, protocol- independent domain and engineering core (engine/), a versioned public SDK boundary (atlas/), a presentation layer that renders read models without touching engine internals (presentation/), and thin client adapters (clients/) that translate an external environment (CLI today; MCP, REST, and IDE integrations are Version 2 scope) into calls against that SDK.

  • atlas/ -- Public Application Platform SDK exposing the Atlas facade, immutable command/result DTOs, and application exceptions.
    • atlas/capabilities/ -- Internal Capability Layer decomposing Atlas into five thin delegation classes -- Project, Workflow, WorkflowExecution, Knowledge, Presentation.
    • atlas/contracts/ -- Public Contract Layer -- versioned RequestEnvelope/ResponseEnvelope, the PlatformErrorCode error contract, and API versioning.
    • atlas/adapters/ -- Public Adapter Boundary -- the structural PlatformAdapter protocol and capability-negotiation manifest every client (CLI, IDE, MCP, AI, REST, Desktop) satisfies.
  • engine/domain/ -- Strongly-typed, framework-independent Pydantic models representing the ubiquitous domain language of ATLAS, including the Engineering Design Language (EDL) components (TraceabilityLink, ArtifactMetadata composition, EngineeringReview contracts), AI proposal drafts (ai_drafts.py), and review feedback (ai_feedback.py).
  • engine/project/ -- Project Subsystem: workspace initialization (.atlas/), loading, metadata discovery, and lifecycle states (initialized, active, paused, archived).
  • engine/memory/ -- Memory Subsystem managing dialogue context and history.
  • engine/knowledge/ -- Knowledge Subsystem: the Engineering Knowledge Layer collecting, deduplicating, retrieving (newest-first, or optionally semantic via sqlite-vec), and managing reviewed project-scoped engineering knowledge.
  • engine/workflow/ -- Workflow Subsystem: execution readiness, phase transitions, and lifecycle orchestration.
  • engine/research/ -- Research Subsystem: problem definition, evidence gathering, snapshotting, hypothesis validation.
  • engine/planning/ -- Planning Subsystem: decomposing research into scopes, milestones, epics, tasks, subtasks, and dependencies.
  • engine/architecture/ -- Architecture Subsystem: component modeling, architectural decisions, interface contracts, and risk analysis.
  • engine/evaluation/ -- Evaluation Subsystem: readiness review and stage-completion evaluation.
  • engine/ai/ -- AI Integration Subsystem: protocol adapters (Gemini, Anthropic, OpenAI-compatible, Ollama), context assembly, orchestration, and stateless engineering proposal services.
  • presentation/ -- Presentation Layer: composes typed, immutable Views from the Atlas read-model API and renders them to JSON/Markdown/CLI, independent of any client adapter.
  • clients/ -- Client adapters (CLI today; MCP/IDE/REST are Version 2) translating external execution environments to the public Atlas SDK.
  • shared/ -- Common utilities and cross-cutting concerns.
    • shared/observability/ -- Request-scoped AI usage capture shared by the engine provider boundary and the Atlas request boundary.
  • atlas/observability/ -- Trace schema, request instrumentation, and pluggable exporters for the platform boundary.
  • evals/ -- YAML task loader, benchmark runner, report generation, and baseline regression detection, plus the labelled knowledge-retrieval eval (evals/retrieval/).

Documentation

The full architecture reference, ADRs, and diagrams live under docs/:

Development Setup

ATLAS uses uv for fast, reproducible package and dependency management during development.

Prerequisites

  • Python >= 3.13
  • uv

Installation

git clone https://github.com/sahil-mangla/atlas.git
cd atlas
uv sync
cp .env.example .env

Local Development Workflow

Three tools are pre-configured for code quality:

  • Ruff -- formatting and linting
  • mypy -- strict static type checking
  • pytest -- automated testing and coverage
# Lint and format
uv run ruff check . --fix
uv run ruff format .

# Type check
uv run mypy .

# Test
uv run pytest

# Run the platform benchmark against the configured/default AI provider
uv run python -m evals

Pre-commit Hooks

uv run pre-commit install
uv run pre-commit run --all-files

Continuous Integration

Every push and pull request against main runs the full verification suite (ruff check, ruff format --check, mypy, pytest) via .github/workflows/ci.yml.

Contributing

Issues and pull requests are welcome:

License

MIT

Project Status

ATLAS is at v1.0.0 -- the first tagged release, following the completion of all sixteen planned phases (see CHANGELOG.md and docs/reports/ for the full history, including the seven-sprint Phase 16 production-readiness pass). Version 2 scope -- additional client adapters (MCP, REST, IDE), a published PyPI package, and the performance-review candidates documented in docs/reports/phase-16-sprint-6-performance-review.md -- is not yet started.

About

ATLAS is an AI-native engineering operating system that transforms ideas into production-ready software through structured research, architecture, planning, implementation, verification, and persistent project intelligence.

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages