An AI narrow-agent platform — configure, evaluate, deploy

---

ScopeWeaver is an open-source platform for building narrow AI agents: specialized agent systems designed for a specific domain, with explicit planning, skill retrieval, and controlled execution.

Instead of treating an agent as a single chat loop with a loose collection of tools, ScopeWeaver makes capabilities explicit. Skills are declared, retrieved, validated, and executed against a controlled runtime, so the system stays inspectable as it grows more capable.

Built by URAI, the AI student association at the University of Regensburg and OTH Regensburg.

Current status: ScopeWeaver is in public release preparation.

What Makes ScopeWeaver Distinct

Many current agent frameworks position themselves around orchestration primitives such as tools, workflows, handoffs, memory, guardrails, and tracing. ScopeWeaver is aimed at a more specific problem: building agents whose capabilities, execution path, and runtime state remain explicit.

The platform is built around a few concrete ideas:

• Explicit capability layer: skills are first-class artifacts with contracts, metadata, and execution boundaries, rather than hidden inside prompts
• Retrieval-guided execution: the system selects the right capability for each step instead of relying on ad hoc tool choice alone
• Controlled runtime: actions run against a structured state model or sandbox instead of directly mutating the outside world without review
• Local-first operation: the architecture is designed for on-device models and privacy-sensitive deployments
• Inspectable behavior: planning, execution flow, and state transitions are meant to stay visible rather than disappear behind a single model response

The first demonstrator built on this architecture focuses on file-system tooling, but the platform itself is task-agnostic and can be adapted to domains such as software engineering, document workflows, research and knowledge work, internal operations, business processes, and other structured tool-using systems.

Architecture At A Glance

---
title: System Architecture
config:
  flowchart:
    curve: stepBefore
---
flowchart LR
    subgraph Frontend[Frontend]
        direction TB
        ui[Client UI]
    end

    subgraph API[API Layer]
        direction TB
        api["Run / stream API"]
    end

    subgraph Pipeline[Agent Pipeline]
        direction TB
        thinker[Thinker]
        planner[Planner]
        checker[Checker]
        orchestrator["Orchestrator + Dispatcher"]
    end

    subgraph Runtime[Execution Environment]
        direction TB
        state@{ shape: cyl, label: "Sandbox / state graph" }
        indexes@{ shape: cyl, label: "Skill + content indexes" }
    end

    ollama[Ollama]

    ui <-->|HTTP + WebSocket| api
    api --> thinker
    thinker --> planner
    planner --> checker
    checker --> orchestrator

    planner -->|retrieval| indexes
    orchestrator -->|read / write| state
    orchestrator -->|query / refresh| indexes

    thinker -.->|LLM calls| ollama
    planner -.->|LLM calls| ollama

    classDef frontendLayer fill:#eef4ff,stroke:#4f7cff,stroke-width:2px,color:#111;
    classDef apiLayer fill:#edf9f0,stroke:#2f9e44,stroke-width:2px,color:#111;
    classDef pipelineLayer fill:#fff4e6,stroke:#f08c00,stroke-width:2px,color:#111;
    classDef runtimeLayer fill:#f5f5f5,stroke:#666,stroke-width:2px,color:#111;
    classDef externalLayer fill:#f3f0ff,stroke:#7048e8,stroke-width:2px,color:#111;

    class Frontend frontendLayer
    class API apiLayer
    class Pipeline pipelineLayer
    class Runtime runtimeLayer
    class ollama externalLayer

Loading

At a high level, the frontend handles interaction and visualization, the API bridges the client and runtime, the agent pipeline plans and validates work, and the execution environment holds the controlled state and retrieval indexes the system operates on.

Pipeline stages:

• Thinker: decomposes a user request into ordered steps
• Planner: selects the relevant skills and fills structured parameters
• Checker: validates the generated plan before execution
• Orchestrator + Dispatcher: executes the loop against the controlled runtime

Codebase Structure

The public release is being prepared around the cleaner architecture currently represented by the dev branch:

ScopeWeaver/
├── backend/src/scope_weaver/   Python package (the agent pipeline)
│   ├── core/                   Pydantic contracts + configuration
│   ├── environment/            FileSystemGraph + Sandbox
│   ├── retrieval/              Embedder, VectorStore, Chunker
│   ├── agent/                  Thinker, Planner, Checker, Orchestrator, Dispatcher
│   ├── api/                    FastAPI routes + schemas
│   └── observability/          Logging and tracing
├── skills/                     Skill definitions (`SKILL.md` files)
├── frontend/macos/             SwiftUI macOS app with bundled visualization
├── tests/                      Unit and integration tests
├── docker/                     Container setup
├── docs/                       Architecture diagrams and guides
└── config/default.yaml         Pipeline configuration

Project Status

ScopeWeaver is currently being prepared for its cleaned public release.

At this stage:

• the repository structure is being finalized
• documentation is being rewritten for public consumption
• licensing and contributor governance are being set up
• the first public code drop is being prepared

That means the repository may temporarily contain branding and licensing materials before the full implementation is published.

The release preparation already includes the core licensing files in this repository, and contributor guidance is available in CONTRIBUTING.md.

License

ScopeWeaver Community Edition is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

If you want to use ScopeWeaver under different terms, including proprietary deployment, closed-source modification, OEM redistribution, or other enterprise use cases that do not fit AGPLv3, commercial licensing is available.

Commercial licensing for ScopeWeaver is handled by URAI. Until a dedicated licensing address is published, direct licensing inquiries through the URAI organization.

See LICENSE for the full license text.