Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,8 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
draws on. Its coordinator conversation looks at the project as a whole: it is told about every thread, starts threads
with a brief that the assistant answers there in the background, reads them and marks them done. Each thread is a
conversation about one part of the work, scoped to the project's namespaces. Every answer in a project reads its goal
and instructions. The Projects page, under Chat, starts threads with a brief and shows which are working. Agents
and instructions. Schedules ask a prompt on a schedule, in a new thread each time or the same one. The Projects
page, under Chat, starts threads with a brief and shows which are working. Agents
start and change projects over MCP and the API. ([Projects](docs/projects.md); [checks](docs/requirements.md#work-toward-a-goal-in-projects))
- **Extend the assistant.** Add tools (a prompt, a web request, a graph drawn on the canvas, or sandboxed Python),
skills, hooks and MCP servers, by code, on the canvas or just by asking. Remote MCP servers connect by address, and
Expand Down
2 changes: 2 additions & 0 deletions changelog.d/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,7 @@
a brief, from it, you or an agent, is answered in the background as you, with your tools, approvals and budgets.
The Projects page, at the top of Chat's conversation list, starts a project with just a name, starts threads with a
brief on Enter, shows which are working and marks them done in one click.
Schedules ask a prompt on a schedule, in a new thread each time or the same one, and wait while switched off or the
project is archived; agents set them with the MCP tool `schedule_project`.
`/api/v1/projects` and the MCP tools `list_projects`, `read_project`, `create_project` and
`update_project` do it all for agents ([Projects](docs/projects.md)).
3 changes: 2 additions & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ that take a namespace use this one when none is named, `list_namespaces` and `li
about the server itself (`file_storage`, `monitoring`, `services`, `mcp_servers`, `sandbox_gateway`, `install_settings`
and the ones that change them) aren't there, even for admins. Nor are the person's own conversations (`list_chats`,
`read_chat`, `rename_chat`, `export_chat`) and projects (`list_projects`, `read_project`, `create_project`,
`update_project`), which belong to no namespace. An admin counts as an owner of the namespace there.
`update_project`, `schedule_project`), which belong to no namespace. An admin counts as an owner of the namespace there.

It is off until an owner of the namespace turns it on: **Admin → Namespaces →** the namespace **→ Connect apps**, which
also copies its address, or `PATCH /api/v1/namespaces/<namespace>/integrations` with `{"mcp": true}`, or an agent's
Expand Down Expand Up @@ -104,6 +104,7 @@ For an app that speaks OpenAI's API rather than MCP, the namespace can also answ
| `read_project` | one of them: its goal and instructions, namespaces, coordinator and threads (each one's title, whether it's done and its last message); read a thread with `read_chat` |
| `create_project` | start a project: a name, its goal, instructions and the namespaces it draws on. Needs a write-scope token |
| `update_project` | change a project's name, goal, instructions or namespaces, archive it, mark a thread done, or start a thread. Needs a write-scope token |
| `schedule_project` | ask a prompt in a project on a schedule, in a new thread each time or the same one; change, switch off or remove a schedule. Needs a write-scope token |
| `create_podcast` | make a two-host learning [episode](podcasts.md) about assets or lines in them, with an angle, a length and a style; it's made in the background. Needs a write-scope token and editor access where it goes |
| `get_podcast` | an episode: how far it has got, its script with each line's speaker and the sources it cites (links), and what the fact-check changed |
| `list_feeds` | the RSS and podcast [feeds](feeds.md) your namespaces publish, each with its private address and how many items it holds; with `feed_id`, one feed and its newest items |
Expand Down
31 changes: 24 additions & 7 deletions docs/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ it draws on. Every conversation in it reads all of that, so you don't explain th
Status: **built**: projects with a goal, instructions and one or more namespaces; a coordinator conversation for the
project as a whole, told about every thread, which starts threads with a brief, reads them and marks them done;
threads, each a conversation in the project's namespaces, marked done when finished; briefs answered in the background;
your own conversations brought in or taken out; through the REST API, MCP and the Projects page in the web app.
**Planned**: scheduled threads, chat rooms and email routed to a project, members sharing one, and a project's own
memory.
your own conversations brought in or taken out; schedules that ask a prompt in a new thread each time or the same
one; through the REST API, MCP and the Projects page in the web app. **Planned**: chat rooms and email routed to a
project, members sharing one, and a project's own memory.

## What a project is

Expand Down Expand Up @@ -70,6 +70,17 @@ there (the conversation's choice of them) and the same approvals, every model ca
Stop (`POST /api/v1/chats/{id}/stop`) stops it between steps. If Lens stops while a brief is being answered, the thread
says so within a few minutes, so it's never left waiting: ask again.

## Schedules

A schedule asks a prompt on a schedule, as a brief: "every Monday at 9:00, what did we get done and what's next?". Each
time it starts a new thread, or, with **The same thread each time**, it goes on in one thread it starts the first time.
The schedule is five cron fields (minute, hour, day of month, month, day of week, or `@daily`, `@weekly`...) in a time
zone; the web app uses yours. It is answered as you, with your tools, approvals and budgets, like any brief. A thread
still answering the last time is left to finish, and the schedule says why it didn't ask. Switched off, or while the
project is archived, a schedule waits; it runs again when it's switched on or the project is brought back. If Lens was
off when one was due, it runs once when Lens is back, within `automations.catch_up` (an hour by default). A project has
up to 20 schedules.

## In the web app

**Projects** is at the top of the conversation list in Chat (`/projects`). **New project** asks for a name, the goal
Expand All @@ -79,7 +90,9 @@ field and the threads, open ones first. Type what a thread should work on and pr
background and marked **Working** until the answer is written. Press Enter with the field empty to open a new thread
and ask in it yourself. The box beside a thread marks it done. **Archive** in the project's menu moves it to the
archived list, with Undo. A conversation in a project has a **Project** link at its top, and one answered in the
background shows "Working on it" until its answer arrives.
background shows "Working on it" until its answer arrives. **Ask on a schedule** under **Schedules** adds one: what
to ask, when (from a list, or a cron of your own) and where. The switch beside a schedule turns it off or on, and the
bin removes it, with Undo.

## The API

Expand All @@ -94,15 +107,19 @@ background shows "Working on it" until its answer arrives.
| `POST /api/v1/projects/{id}/threads` | a new thread (`title`), or bring in one of your conversations (`chat`); with a `brief`, asked and answered there in the background |
| `PATCH /api/v1/projects/{id}/threads/{chat}` | mark a thread done, or not (`done`) |
| `DELETE /api/v1/projects/{id}/threads/{chat}` | take a thread out of the project |
| `POST /api/v1/projects/{id}/schedules` | ask a `prompt` on a schedule (`cron`, `timezone`), in a new thread each time or the same one (`thread`: `new` or `same`) |
| `PATCH /api/v1/projects/{id}/schedules/{schedule}` | change a schedule, or switch it off or on (`on`) |
| `DELETE /api/v1/projects/{id}/schedules/{schedule}` | remove a schedule; the threads it started stay |

Ask in a thread or the coordinator as in any conversation: `POST /api/v1/chats/{chat}/messages`
([API](api.md)). Over [MCP](mcp.md), `list_projects`, `read_project`, `create_project` and `update_project` do the
same for agents; the last two need a token with the write scope.
([API](api.md)). Over [MCP](mcp.md), `list_projects`, `read_project`, `create_project`, `update_project` and
`schedule_project` do the same for agents; the last three need a token with the write scope.

## Refine later

- Threads answering their briefs at the same time as each other, with a limit per person.
- Scheduled threads: a prompt asked on a schedule, in a new thread each time or the same one.
- The coordinator setting schedules itself, after the person's yes.
- Project schedules on the Schedules page, beside routines, automations and the backup.
- Deleting a project from the web app (the API and MCP can), with Undo.
- A project's threads in the Chat sidebar, grouped under it.
- Chat rooms, Telegram, Slack and email routed to a project.
Expand Down
3 changes: 3 additions & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,9 @@ request, to another check that proves the same thing; loosening a requirement or
| The coordinator starts threads with a brief, reads them and marks them done; a thread can't start threads; it asks first after reading outside text, and starts a few per answer at most | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_the_coordinator_starts_threads_with_a_brief`, `test_starting_threads_after_reading_outside_text_asks_first` |
| A brief from the person, an agent or the coordinator is answered in the background as the person; one cut off by a stopped process is marked, never left waiting | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_a_brief_from_the_api_or_an_agent_is_answered_in_the_background`, `test_a_brief_cut_off_by_a_stop_is_marked_by_the_sweep` |
| The Projects page starts a project with just a name, starts threads with a brief on Enter, shows which are working and marks them done in one click; projects sit under Chat | [projects.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/projects.test.tsx) `starts one in the current namespace with just a name, then opens it`, `starts a thread with a brief on Enter and keeps the page`, `marks a thread done with one click`, `are under Chat in the navigation` |
| A schedule asks its prompt as a brief in a new thread each time or always the same one, and leaves a thread still answering to finish | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_a_schedule_asks_its_prompt_in_a_new_thread_or_the_same_one` |
| Schedules wait while switched off or the project is archived, are their owner's alone, end with the project, and agents set them over MCP | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_schedules_wait_while_off_or_archived_and_agents_set_them` |
| The project page adds a schedule from a list in the person's time zone, switches one off in a click and removes one with Undo | [projects.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/projects.test.tsx) `asks on a schedule picked from a list, in the person's time zone`, `shows when each runs, switches one off in a click and removes one with Undo` |
| Agents list, read, start and change projects over MCP | [test_projects.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_projects.py) `test_agents_use_projects_over_mcp` |

## Extend the assistant
Expand Down
72 changes: 71 additions & 1 deletion fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,14 @@
from app.schemas.entities import EntityHide, EntityList, EntityRename, EntityRetype, EntityUpdate
from app.schemas.jobs import JobMove, JobsPick
from app.schemas.notebook import NotePage
from app.schemas.projects import ProjectCreate, ProjectUpdate, ThreadCreate, ThreadUpdate
from app.schemas.projects import (
ProjectCreate,
ProjectScheduleCreate,
ProjectScheduleUpdate,
ProjectUpdate,
ThreadCreate,
ThreadUpdate,
)
from app.schemas.schedules import ScheduleChange, ScheduleRun
from app.schemas.search import SearchResults
from app.schemas.topics import TopicMerge, TopicUpdate
Expand Down Expand Up @@ -2039,6 +2046,22 @@ def _project(ctx: Context, p: Any, threads: bool = True) -> dict[str, Any]:
)
for t in d.get("thread_list") or []
]
out["schedules"] = [
store.clean(
{
"schedule_id": sc["id"],
"prompt": sc["prompt"],
"cron": sc["cron"],
"timezone": sc["timezone"],
"thread": sc["thread"],
"on": sc["on"],
"when": sc["when"],
"next_at": sc.get("next_at"),
"last": sc.get("last"),
}
)
for sc in d.get("schedules") or []
] or None
return store.clean(out)


Expand Down Expand Up @@ -2141,6 +2164,53 @@ def update_project(
return out


@tool(
"schedule_project",
"Ask on a schedule in a project",
"Ask a prompt in one of your projects on a schedule (cron: five fields, like 0 8 * * 1-5 for 8:00 on weekdays), "
"in a new thread each time or always the same one; Lens's assistant answers it in the background as you. With "
"schedule_id, change that schedule instead, switch it off or on (on), or remove it (remove). Needs a token with "
"the write scope.",
Arg("project_id", "integer", "the project (from list_projects)", required=True),
Arg("schedule_id", "string", "a schedule to change or remove (from read_project)", max_length=20),
Arg("prompt", "string", "what to ask each time", max_length=4000),
Arg("cron", "string", "when, as five cron fields or @daily, @weekly...", max_length=200),
Arg("timezone", "string", "the time zone it's in, like Europe/London (UTC when left out)", max_length=64),
Arg("thread", "string", "new: a new thread each time; same: always the same one", enum=("new", "same")),
Arg("on", "boolean", "with schedule_id: switch it on or off"),
Arg("remove", "boolean", "with schedule_id: remove it"),
writes=True,
personal=True,
)
def schedule_project(
ctx: Context,
project_id: int,
schedule_id: str | None,
prompt: str | None,
cron: str | None,
timezone: str | None,
thread: str | None,
on: bool | None,
remove: bool | None,
) -> dict[str, Any]:
_writer(ctx, "change projects")
if schedule_id is None:
if not prompt or not cron:
raise ToolError("give prompt and cron for a new schedule, or schedule_id to change one")
body = ProjectScheduleCreate(prompt=prompt, cron=cron, timezone=timezone or "UTC", thread=thread or "new")
sid = project_routes.add_schedule(project_id, body, ctx.user, ctx.db).id
elif remove:
project_routes.remove_schedule(project_id, schedule_id, ctx.user, ctx.db)
sid = None
else:
changes = {"prompt": prompt, "cron": cron, "timezone": timezone, "thread": thread, "on": on}
sid = project_routes.update_schedule(project_id, schedule_id, ProjectScheduleUpdate(**store.clean(changes)), ctx.user, ctx.db).id
out = _project(ctx, project_routes.get_project(project_id, ctx.user, ctx.db))
if sid is not None:
out["schedule_id"] = sid
return out


# ---------- podcasts ----------
@tool(
"create_podcast",
Expand Down
54 changes: 52 additions & 2 deletions fastapi_backend/app/api/v1/routes/projects.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,18 @@
from app.domain import projects
from app.domain.store import DB
from app.schemas.common import Created, Ok
from app.schemas.projects import Project, ProjectCreate, ProjectSummary, ProjectThread, ProjectUpdate, ThreadCreate, ThreadUpdate
from app.schemas.projects import (
Project,
ProjectCreate,
ProjectSchedule,
ProjectScheduleCreate,
ProjectScheduleUpdate,
ProjectSummary,
ProjectThread,
ProjectUpdate,
ThreadCreate,
ThreadUpdate,
)

router = APIRouter(prefix="/projects", tags=["projects"])

Expand Down Expand Up @@ -41,7 +52,7 @@ def summary(db: DB, p: dict[str, Any], threads: list[dict[str, Any]] | None = No
def view(db: DB, p: dict[str, Any]) -> Project:
projects.coordinator(db, p) # made again if its conversation was deleted
threads = projects.threads(db, p)
return Project.model_validate({**summary(db, p, threads), "thread_list": threads})
return Project.model_validate({**summary(db, p, threads), "thread_list": threads, "schedules": projects.schedules(db, p)})


@router.get("")
Expand Down Expand Up @@ -143,3 +154,42 @@ def release_thread(pid: int, cid: int, user: Writer, db: Db) -> Ok:
except ValueError as e:
raise HTTPException(400, str(e)) from None
return Ok()


def _one(db: DB, p: dict[str, Any], sid: str) -> ProjectSchedule:
return ProjectSchedule.model_validate(next(s for s in projects.schedules(db, p) if s["id"] == sid))


@router.post("/{pid}/schedules")
def add_schedule(pid: int, body: ProjectScheduleCreate, user: Writer, db: Db) -> ProjectSchedule:
"""Ask a prompt on a schedule: each time, in a new thread or always the same one, answered in the background as
you, with your tools, approvals and budgets."""
p = own(db, pid, user)
try:
sc = projects.add_schedule(db, p, body.prompt, body.cron, body.timezone, body.thread)
except ValueError as e:
raise HTTPException(400, str(e)) from None
return _one(db, p, sc["id"])


@router.patch("/{pid}/schedules/{sid}")
def update_schedule(pid: int, sid: str, body: ProjectScheduleUpdate, user: Writer, db: Db) -> ProjectSchedule:
"""Change a schedule, or switch it off or on."""
p = own(db, pid, user)
try:
projects.update_schedule(db, p, sid, body.prompt, body.cron, body.timezone, body.thread, body.on)
except KeyError:
raise HTTPException(404, "no such schedule in this project") from None
except ValueError as e:
raise HTTPException(400, str(e)) from None
return _one(db, p, sid)


@router.delete("/{pid}/schedules/{sid}")
def remove_schedule(pid: int, sid: str, user: Writer, db: Db) -> Ok:
"""Remove a schedule. The threads it started stay."""
try:
projects.remove_schedule(db, own(db, pid, user), sid)
except KeyError:
raise HTTPException(404, "no such schedule in this project") from None
return Ok()
Loading
Loading